[MAJOR] §11: mojo-language-review-specialist.md referenced but does not exist

[mvillmow]

Finding

Severity: MAJOR
Section: 11
Evidence: .claude/agents/architecture-design.md (line referencing mojo-language-review-specialist.md)
Principle: POLA

The architecture-design agent instructs 'When working with Mojo code, follow patterns in ./mojo-language-review-specialist.md' but this file does not exist in .claude/agents/. Dead references in agent configuration files cause agents to fail when they attempt to follow instructions that reference nonexistent resources.

---

Part of #504

[mvillmow]

Implementation Plan

Now I have a complete picture. Here's the implementation plan:

---

Implementation Plan: Issue #519 — Remove Dead mojo-language-review-specialist.md References

1. Objective

Remove all 26 dead references to the non-existent .claude/agents/mojo-language-review-specialist.md across 24 agent configuration files. The file was deleted (or never created), and all inline links and delegation entries pointing to it must be cleaned up so agents don't fail when following their instructions.

---

2. Approach

Remove the dead references, do not recreate the file. ProjectKeystone is a pure C++20 project (per CLAUDE.md). Mojo is not part of this project's stack. The referenced file was never applicable here — the references are copy-paste artifacts from a Mojo-focused project. The correct fix is surgical removal of each reference, not creating a stub file.

Two reference patterns appear:

• Inline narrative references (most files): A sentence like "When working with Mojo code, follow patterns in mojo-language-review-specialist.md. Key principles: prefer fn over def, ..." — remove the entire sentence/paragraph.
• Delegation list entries (code-review-orchestrator.md lines 401, 755): Bullet list items - [Mojo Language Review Specialist](./mojo-language-review-specialist.md) - ... — remove the bullet line and update any surrounding count labels.

---

3. Files to Create

None. No new files needed.

---

4. Files to Modify

24 agent files each containing one reference (except code-review-orchestrator.md which has 2):

File	Line	Pattern
.claude/agents/architecture-design.md	241–243	Inline narrative paragraph
.claude/agents/agentic-workflows-orchestrator.md	~201	Inline narrative paragraph
.claude/agents/cicd-orchestrator.md	~238	Inline narrative paragraph
.claude/agents/documentation-engineer.md	~181	Inline narrative paragraph
.claude/agents/documentation-specialist.md	~N	Inline narrative paragraph
.claude/agents/foundation-orchestrator.md	~N	Inline narrative paragraph
.claude/agents/implementation-specialist.md	~N	Inline narrative paragraph
.claude/agents/integration-design.md	~243	Inline narrative paragraph
.claude/agents/junior-documentation-engineer.md	~N	Inline narrative paragraph
.claude/agents/junior-implementation-engineer.md	~N	Inline narrative paragraph
.claude/agents/junior-test-engineer.md	~N	Inline narrative paragraph
.claude/agents/papers-orchestrator.md	~N	Inline narrative paragraph
.claude/agents/performance-engineer.md	~N	Inline narrative paragraph
.claude/agents/performance-specialist.md	~N	Inline narrative paragraph
.claude/agents/security-design.md	~196	Inline narrative paragraph
.claude/agents/security-specialist.md	~N	Inline narrative paragraph
.claude/agents/senior-implementation-engineer.md	~N	Inline narrative paragraph
.claude/agents/shared-library-orchestrator.md	~N	Inline narrative paragraph
.claude/agents/test-engineer.md	~N	Inline narrative paragraph
.claude/agents/test-specialist.md	~N	Inline narrative paragraph
.claude/agents/tooling-orchestrator.md	~N	Inline narrative paragraph
.claude/agents/performance-review-specialist.md	~716	Delegation list bullet
.claude/agents/safety-review-specialist.md	~661	Delegation list bullet
.claude/agents/code-review-orchestrator.md	401, 755	Delegation list bullet (×2); check count labels

Specific edits for architecture-design.md (lines 241–243):
Remove:

When working with Mojo code, follow patterns in
[mojo-language-review-specialist.md](./mojo-language-review-specialist.md). Key principles: prefer `fn` over `def`, use
`owned`/`borrowed` for memory safety, leverage SIMD for performance-critical code.

(The entire "## Language Guidelines" section may become empty — remove the section header too if it has no other content.)

Specific edits for code-review-orchestrator.md (lines 401, 755):
Remove bullet: - [Mojo Language Review Specialist](./mojo-language-review-specialist.md) - Mojo-specific patterns
Remove bullet: - [Mojo Language Review Specialist](./mojo-language-review-specialist.md) - Mojo-specific features and idioms
Check if any nearby count label (e.g., "Review Specialists (10)") needs decrementing.

---

5. Implementation Order

1. Read each affected file to see the full context around the reference before editing (ensures correct removal without breaking surrounding structure).
2. Edit all 21 "inline narrative" files in parallel — each has the same pattern, independent edits.
3. Edit code-review-orchestrator.md separately — it has two bullet removals and may have count labels to update.
4. Edit performance-review-specialist.md and safety-review-specialist.md — delegation list bullet removal.
5. Verify no references remain: grep -rn "mojo-language-review-specialist" .claude/agents/
6. Run markdownlint on changed files to confirm no MD013/MD022/MD024/MD032 violations.
7. Run pre-commit on all changed files.

---

6. Verification

# Confirm zero remaining references
grep -rn "mojo-language-review-specialist" .claude/agents/
# Expected: no output

# Run pre-commit on all changed agent files
pre-commit run --files $(git diff --name-only HEAD)

# If validate_configs.py exists (it doesn't currently, but if added):
python3 tests/agents/validate_configs.py .claude/agents/

Since tests/agents/validate_configs.py does not exist in this repo, no test file needs to be created for this fix — the verification is the grep returning empty.

---

7. Skills Used

Invoked during planning:

• None invoked directly (used Grep/Read tools directly for this scoped lookup)

Team knowledge base skills referenced from Prior Learnings:

• fix-stale-agent-crossrefs — pattern for removing dead markdown cross-references in .claude/agents/
• update-stale-agent-references — searching the full repo (not just .claude/agents/) for stale references
• delegates-to-file-existence-check — validation pattern after fix
• agent-validate-config — general agent config validation approach

Key lessons applied:

• Search the full repo, not just .claude/agents/ (the grep confirmed references exist in 24 files)
• Remove the dead reference rather than recreating the nonexistent file
• Check count labels in orchestrator files after removing list bullets
• Keep replacement text under 120 chars (markdownlint MD013)
• All 24 files are independent — parallel edits are safe

---

Generated by Claude Code Planner