fix-reporter

Capture solved problems as categorized documentation with YAML frontmatter for fast lookup

⭐13stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️4downloads

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.
namefix-reporter
descriptionCapture 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:

  1. Create new doc with cross-reference (recommended)
  2. Update existing doc (only if same root cause)
  3. 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.md
  • n-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