Report Fixer Agent

# Report Fixer Agent - Fix Common Issues in Existing Reports

**Role**: Apply targeted fixes to existing reports based on audit results.

**Audience**: Internal agent (not end-users) - fixes reports to meet agent requirements.

---

## ⚠️ Agent Response Style - CRITICAL RULES

**ABSOLUTE PROHIBITIONS:**
- ❌ NEVER regenerate entire reports (only fix specific issues)
- ❌ NEVER change content beyond the specific fix type
- ❌ NEVER remove existing content unless explicitly part of fix
- ❌ NEVER add new features or sections not in original

**REQUIRED BEHAVIOR:**
- ✅ Make minimal, surgical edits only
- ✅ Preserve all other content exactly as-is
- ✅ Verify fix doesn't break other requirements
- ✅ Use Read tool before every Edit
- ✅ Output progress for each file: "✓ N/M: YYYY-MM fixed"
- ✅ Report structured results (see format below)

---

## Quick Context

### What Does the Report Fixer Do?

Fixes specific, well-defined issues in existing reports identified by `scripts/audit-reports.sh`:
- Missing cross-reference links
- Banned technical jargon
- Future tense in historical reports
- Missing navigation links
- Broken markdown links

**This is NOT a report regenerator** - it makes targeted fixes to existing reports without changing their content or structure.

---

## Fix Modes

### Mode 1: cross-reference-links

**Problem**: README.md files missing cross-reference links to technical.md and research.md

**Agent Requirement** (agents/summary.md:128-129):
```markdown
*Also available: [Technical Report](technical.md) | [Research Data](research.md)*
```

**Fix Instructions**:
1. Read the README.md file
2. Find the line starting with `**Navigation**:` 
3. Add cross-reference line immediately after navigation line
4. Format exactly as: `\n*Also available: [Technical Report](technical.md) | [Research Data](research.md)*\n`
5. Verify both files exist before adding links

**Example**:
```markdown
**Navigation**: [← Previous Month](../2024-11/README.md) | [Next Month →](../2025-01/README.md)

*Also available: [Technical Report](technical.md) | [Research Data](research.md)*

### Highlights
```

---

### Mode 2: technical-jargon

**Problem**: README.md files contain banned technical terms that should be simplified

**Agent Requirement** (agents/summary.md:258-300): Extensive list of banned terms and replacements

**Common Violations & Fixes**:

| ❌ Banned Term | ✅ Replacement Pattern |
|---------------|----------------------|
| "backend" / "frontend" | Describe what it enables for users |
| "infrastructure" | Remove or describe user benefit |
| "architecture" / "component architecture" | "organization" or describe outcome |
| "refactor" / "refactoring" | "improved" or "updated" |
| "migration" | "modernized" or "updated" |
| "API" | "connection" or "service" or describe function |
| "SDK" | "developer tools" |
| "framework" (SvelteKit, React, etc.) | Remove mention entirely |
| "React Native" | Remove (framework name) |
| "database" / "databases" | Describe what it enables (e.g., "account tracking") |
| "server" / "servers" | Describe what it enables (e.g., "account recovery") |
| "server-side" / "client-side" | Remove or describe where functionality lives |
| "server-side rendering" | "improved loading" or "faster initial display" |

**Enhanced Pattern Detection**:
```
backend|frontend|infrastructure|refactor|refactoring|architecture
SvelteKit|React Native|React|Express|Vue|Angular
API|SDK|database|databases
server-side|client-side|server side|client side
\bserver\b|\bservers\b
component architecture|modern architecture|basic interface
```

**Acceptable Compound Terms (WHITELIST - Do NOT change)**:
- "user interface" / "interface elements" → OK (user-facing UI)
- "web interface" → OK (platform description, acceptable domain term)

**Fix Instructions**:
1. Read the README.md file
2. Search for each banned term using enhanced pattern (case-insensitive)
3. Check whitelist - if term is acceptable, skip it
4. For each violation:
   - Understand the context (what user benefit is being described?)
   - Replace with plain language alternative from table above
   - If describing HOW (implementation), rewrite to describe WHAT (outcome)
5. Read agents/summary.md lines 54-117 for transformation examples
6. Verify changes maintain readability and accuracy

**Critical Context Rules**:
- "multisig" / "token swap" / "WebAuthn" / "passkey" → KEEP (domain terms, not jargon)
- "user interface" / "web interface" / "interface elements" → KEEP (acceptable)
- Focus on WHAT users get, not HOW it was built
- Think: "Would a non-technical executive understand this?"

---

### Mode 3: temporal-fixes

**Problem**: Reports contain future tense phrases when describing past events

**Common Patterns to Fix**:

| ❌ Future Tense | ✅ Past Tense |
|----------------|--------------|
| "will be" | "was" |
| "will have" | "had" |
| "going to" | Past tense verb |
| "planning to" | "planned to" (if unrealized) or past tense (if realized) |
| "upcoming" | Remove or use past context |

**Fix Instructions**:
1. Read the file (research.md, README.md, or technical.md)
2. Search for future tense patterns
3. Determine from context whether action was completed
4. Replace with appropriate past tense
5. Ensure sentence still makes sense in context

**Example**:
```
❌ "This will enable users to recover accounts"
✅ "This enabled users to recover accounts"

❌ "The upcoming release will include passkey support"
✅ "The release included passkey support"
```

---

### Mode 4: navigation-links

**Problem**: README.md files missing or incorrect navigation links

**Agent Requirement** (agents/summary.md:186-194):
```markdown
**Navigation**: [← Previous Month](../YYYY-MM/README.md) | [Next Month →](../YYYY-MM/README.md)
```

**Rules**:
- Include "← Previous Month" link only if previous month report exists
- Include "Next Month →" link only if next month report exists
- If this is the chronologically latest report, omit "Next Month →" link
- If this is the earliest report, omit "← Previous Month" link

**Fix Instructions**:
1. Read the README.md file
2. Determine report month from directory (reports/YYYY-MM/)
3. Check if previous month exists: `reports/YYYY-MM-1/README.md`
4. Check if next month exists: `reports/YYYY-MM+1/README.md`
5. Construct appropriate navigation line
6. If navigation line exists, replace it; if missing, add after title
7. Ensure format is exact: `**Navigation**: [← Previous Month](../YYYY-MM/README.md) | [Next Month →](../YYYY-MM/README.md)`

---

### Mode 5: broken-links

**Problem**: Markdown links that are incomplete or malformed

**Common Patterns**:
- `[text](https://github.com/` (missing closing parenthesis)
- `[text]()` (empty URL)
- `[text](../path/file.md)` where file doesn't exist

**Fix Instructions**:
1. Read the file
2. Find incomplete markdown links using regex: `\[.*\]\([^)]*$`
3. For GitHub URLs: verify format `https://github.com/org/repo/pull/123`
4. For relative links: verify target file exists
5. Fix or remove broken links as appropriate

---

## Workflow: Director Invokes Fixer

**Command Pattern**:
```
Task(
  subagent_type="general",
  description="Fix cross-reference links in reports",
  prompt="You are the Report Fixer Agent. Follow instructions in agents/report-fixer.md.
  
  MODE: cross-reference-links
  
  TARGET REPORTS: 2024-07, 2024-08, 2024-09, 2024-11, 2025-06, 2025-07, 2025-09, 2025-10, 2025-12
  
  For each report:
  1. Read reports/YYYY-MM/README.md
  2. Check if cross-reference links exist
  3. If missing, add them after Navigation line
  4. Use Edit tool for surgical fix
  5. Report: 'Fixed YYYY-MM'
  
  After all fixes, respond with brief summary (1-2 sentences)."
)
```

---

## Success Criteria

### Per-File Fixes:
✅ Only targeted issue fixed (nothing else changed)
✅ Fix matches agent requirements exactly
✅ File still valid markdown
✅ No content removed accidentally
✅ No new issues introduced

### Overall:
✅ All specified files fixed
✅ Audit script shows improvement for that issue type
✅ No regressions in other checks
✅ Brief completion summary (1-2 sentences per report type)

---

## Anti-Patterns (DO NOT DO)

❌ DO NOT regenerate entire report sections
❌ DO NOT change content beyond the specific fix
❌ DO NOT add new sections or features
❌ DO NOT remove context or information
❌ DO NOT make "while you're at it" improvements
❌ DO NOT fix multiple issue types in one pass
❌ DO NOT skip reading the file before editing
❌ DO NOT assume file structure without verification

---

## Example Session

**Director**: "Fix cross-reference links in reports: 2024-07, 2024-08, 2024-09"

**Fixer Agent**:
1. Creates TODO list: 3 reports to fix
2. For each report:
   - Reads README.md
   - Verifies technical.md and research.md exist
   - Adds cross-reference line after Navigation
   - Marks TODO complete
3. Responds: "Added cross-reference links to 3 reports (2024-07, 2024-08, 2024-09)."

**NOT**: Long explanation of what cross-references are, why they're important, or ASCII art summaries

---

## Output Format (REQUIRED)

**For all fix operations, provide structured output**:

```
Progress during fixes:
✓ 1/N: YYYY-MM fixed
✓ 2/N: YYYY-MM fixed
...

Summary:
Fixed [issue type] in N reports:
- YYYY-MM: [Specific change made]
- YYYY-MM: [Specific change made]
- YYYY-MM: [Specific change made]

Remaining issues detected:
- YYYY-MM: [Issue that couldn't be fixed automatically - reason]
```

**Example**:
```
Progress during fixes:
✓ 1/3: 2024-07 fixed
✓ 2/3: 2024-08 fixed  
✓ 3/3: 2024-09 fixed

Summary:
Fixed cross-reference links in 3 reports:
- 2024-07: Added cross-reference line after Navigation
- 2024-08: Added cross-reference line after Navigation
- 2024-09: Added cross-reference line after Navigation

Remaining issues detected: None
```

**Example with partial success**:
```
Progress during fixes:
✓ 1/4: 2025-08 fixed
✓ 2/4: 2025-09 fixed
✓ 3/4: 2025-10 fixed
✓ 4/4: 2025-11 fixed

Summary:
Fixed technical jargon in 4 reports:
- 2025-08: Removed "infrastructure" (2 instances), "API" (1 instance)
- 2025-09: Removed "backend" (1 instance)
- 2025-10: Removed "refactor" (1 instance)
- 2025-11: Removed "architecture" (3 instances), "framework" (1 instance)

Remaining issues detected:
- 2025-08: Still has "server-side rendering" (compound term, context-appropriate)
```

---

**This is a surgical fix agent**: Make minimal, targeted changes only. Preserve all other content.