| name | fix-reporter |
| description | Capture solved problems as categorized documentation with YAML frontmatter for fast lookup |
| allowed-tools | Read Write Bash Grep |
| preconditions | ["Problem has been solved (not in-progress)","Solution has been verified working"] |
fix-reporter Skill
Purpose: Document solved problems to build searchable institutional knowledge.
Organization: Single-file per problem in .agents/lessons/[category]/[filename].md with YAML frontmatter. Files with workflow_phase fields are discoverable by lessons-discoverer agent.
7-Step Capture Process
Step 1: Detect Confirmation
Auto-invoke triggers:
- "that worked", "it's fixed", "working now", "problem solved", "that did it"
Manual: /report-fix command
Document when:
- Multiple investigation attempts needed
- Tricky debugging that took time
- Non-obvious solution
- Future sessions would benefit
Skip for: Simple typos, obvious syntax errors, trivial fixes
Step 2: Gather Context
Extract from conversation:
| Field | Source |
|---|
| Module name | Which project module had the problem |
| Symptom | Observable error/behavior (exact messages) |
| Investigation attempts | What didn't work and why |
| Root cause | Technical explanation |
| Solution | Code/config changes that fixed it |
| Prevention | How to avoid in future |
If critical context missing: Ask user and WAIT before Step 3.
Step 3: Check Existing Docs
grep -r "exact error phrase" .agents/lessons/
ls .agents/lessons/[category]/
If similar found: Present options:
- Create new doc with cross-reference (recommended)
- Update existing doc (only if same root cause)
- Other
If not found: Proceed to Step 4.
Step 4: Generate Filename
Format: [sanitized-symptom]-[module]-[YYYYMMDD].md
Rules:
- Lowercase, hyphens for spaces
- Remove special characters
- Truncate < 80 chars
Examples:
missing-import-auth-module-20251110.mdn-plus-one-user-queries-UserService-20251110.md
Step 5: Validate YAML Schema
Validate against schema.yaml and references/yaml-schema.md.
Required fields:
- module, date, problem_type, component
- symptoms (array 1-5), root_cause
- resolution_type, severity
BLOCK if validation fails - show errors, request corrections.
Step 6: Create Documentation
CATEGORY="[mapped from problem_type]"
mkdir -p .agents/lessons/${CATEGORY}
Populate assets/resolution-template.md with:
- Context from Step 2
- Validated YAML from Step 5
Optional discovery fields: Add workflow_phase, tech_stack, lesson_type, impact, keywords if lesson should auto-surface.
Step 7: Cross-Reference
If similar issues from Step 3:
- Add "Related Issues" links to both docs
If 3+ similar issues exist:
- Consider adding to
.agents/lessons/patterns/common-solutions.md
If severity=critical + non-obvious solution:
- Note in output: "Consider adding to Critical Patterns"
Output
After capture, invoke fix-decision-router skill with:
doc_path: .agents/lessons/[category]/[filename].md
category: [problem_type category]
Category Mapping
| problem_type | Directory |
|---|
| build_error | build-errors/ |
| test_failure | test-failures/ |
| runtime_error | runtime-errors/ |
| performance_issue | performance-issues/ |
| database_issue | database-issues/ |
| security_issue | security-issues/ |
| ui_bug | ui-bugs/ |
| integration_issue | integration-issues/ |
| logic_error | logic-errors/ |
| developer_experience | developer-experience/ |
| workflow_issue | workflow-issues/ |
| best_practice | best-practices/ |
| documentation_gap | documentation-gaps/ |
Success Criteria
Error Handling
| Error | Action |
|---|
| Missing context | Ask user, WAIT |
| YAML validation fail | Show errors, BLOCK until valid |
| Similar issue ambiguity | Present options, let user choose |
Quality Guidelines
Include:
- Exact error messages (copy-paste)
- File:line references
- Observable symptoms
- Failed attempts documented
- Technical "why" explanation
- Code examples (before/after)
- Prevention guidance
Avoid:
- Vague descriptions
- Missing technical details
- No context (version, file)
- Code dumps without explanation
