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