fix-reporter
Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
When & Why to Use This Skill
The fix-reporter skill is a specialized tool designed to automate the creation of structured technical documentation for solved problems. By capturing symptoms, root causes, and resolutions with validated YAML frontmatter, it transforms ephemeral debugging sessions into a searchable, permanent institutional knowledge base. This skill ensures that non-obvious solutions are preserved, preventing repetitive troubleshooting and accelerating future development cycles.
Use Cases
- Automated Post-Mortem Documentation: Instantly generate a 'lesson learned' report after a successful bug fix by triggering the skill with phrases like 'it's fixed' or 'that worked'.
- Technical Debt Reduction: Build a centralized repository of complex debugging history in `.agents-os/lessons/`, allowing teams to identify recurring patterns and systemic architectural issues.
- Developer Onboarding: Provide new team members with a searchable database of past technical hurdles and their specific, verified solutions to flatten the learning curve of a complex codebase.
- Cross-Reference Troubleshooting: Use the skill's automated grep functionality to check if a current error has been solved previously, linking related issues to provide comprehensive context for developers.
| name | fix-reporter |
|---|---|
| description | Capture solved problems as categorized documentation with YAML frontmatter for fast lookup |
fix-reporter Skill
Purpose: Document solved problems to build searchable institutional knowledge.
Organization: Single-file per problem in .agents-os/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
# Search for similar issues
grep -r "exact error phrase" .agents-os/lessons/
ls .agents-os/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-os/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-os/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-os/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
- YAML frontmatter validated
- File created in
.agents-os/lessons/[category]/ - Enum values match schema exactly
- Code examples included
- Cross-references added if related issues found
- fix-decision-router invoked
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