fix-reporter Skill

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:

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

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

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