用途：把一次排查成功的问题沉淀为可检索的机构知识。每个问题生成单个文件，存放在 .agents/lessons/[category]/[filename].md，带 YAML frontmatter；含 workflow_phase 字段的文件可被 lessons-discoverer 代理发现。
触发与判断：自动触发语包括 "that worked"、"it's fixed"、"working now"、"problem solved"、"that did it"，也可用 /report-fix 命令手动触发。适合记录需要多次尝试、排查耗时、解决方案不直观、对未来会话有用的案例；简单拼写错误、明显语法错误、琐碎修复可跳过。
七步流程：1）识别确认；2）从对话中收集模块名、症状（精确报错信息）、失败尝试、根因、解决方案、预防措施，缺失关键上下文时先询问用户并等待；3）用 grep -r "exact error phrase" .agents/lessons/ 和 ls .agents/lessons/[category]/ 查重，有相似则选择新建并交叉引用、仅在根因相同时更新现有文档；4）生成文件名，格式为 [sanitized-symptom]-[module]-[YYYYMMDD].md，全小写、空格转连字符、去除特殊字符、截断在 80 字符内；5）按 schema.yaml 与 references/yaml-schema.md 校验 YAML，必填 module、date、problem_type、component、symptoms（1-5 项数组）、root_cause、resolution_type、severity，校验失败则阻塞并提示错误；6）用 mkdir -p .agents/lessons/${CATEGORY} 建目录，按 assets/resolution-template.md 填充内容，可选加入 workflow_phase、tech_stack、lesson_type、impact、keywords 以便自动浮现；7）添加 Related Issues 交叉链接，相似问题达 3 个以上可汇总到 .agents/lessons/patterns/common-solutions.md，severity=critical 且方案不直观时提示考虑加入 Critical Patterns。完成后调用 fix-decision-router 技能，参数为 doc_path 与 category。
分类目录映射：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/。
质量要求：包含可复制的精确报错、file:line 引用、可观察症状、失败尝试、技术原因、前后代码示例与预防建议；避免描述含糊、缺技术细节、无版本或文件上下文、无解释的代码堆砌。具体收费、平台支持、安装命令等暂未提供。