fix-reporter

fix-reporter 技能

用途： 记录已解决的问题，构建可搜索的组织知识库。

组织方式： 每个问题单独存放在 .agents/lessons/[category]/[filename].md 文件中，并使用 YAML frontmatter。带有 workflow_phase 字段的文件可由 lessons-discoverer Agent 发现。

7 步记录流程

步骤 1：检测确认

自动调用触发词：

• “that worked”、“it's fixed”、“working now”、“problem solved”、“that did it”

手动调用： /report-fix 命令

以下情况需要记录：

• 需要多次尝试调查
• 耗时较长、棘手的调试
• 不明显的解决方案
• 记录下来有助于后续会话

以下情况无需记录： 简单的拼写错误、明显的语法错误、微不足道的修复

步骤 2：收集上下文

从对话中提取：

字段	来源
模块名称	出现问题的项目模块
症状	可观察到的错误或行为（具体消息）
调查尝试	哪些尝试无效以及原因
根本原因	技术说明
解决方案	修复问题的代码或配置更改
预防措施	如何避免问题再次发生

如果缺少关键信息： 向用户询问，并等待回复后再进行步骤 3。

步骤 3：检查现有文档

# Search for similar issues
grep -r "exact error phrase" .agents/lessons/
ls .agents/lessons/[category]/

如果找到类似问题： 提供以下选项：

1. 创建带有交叉引用的新文档（推荐）
2. 更新现有文档（仅限根本原因相同的情况）
3. 其他

如果未找到： 继续步骤 4。

步骤 4：生成文件名

格式：[sanitized-symptom]-[module]-[YYYYMMDD].md

规则：

• 使用小写字母，以连字符替代空格
• 删除特殊字符
• 截断至少于 80 个字符

示例：

• missing-import-auth-module-20251110.md
• n-plus-one-user-queries-UserService-20251110.md

步骤 5：验证 YAML 架构

根据 schema.yaml 和 references/yaml-schema.md 进行验证。

必填字段：

• module、date、problem_type、component
• symptoms（数组，1–5 项）、root_cause
• resolution_type、severity

验证失败时必须阻止后续操作——显示错误并请求修正。

步骤 6：创建文档

CATEGORY="[mapped from problem_type]"
mkdir -p .agents/lessons/${CATEGORY}

使用以下内容填充 assets/resolution-template.md：

• 步骤 2 中的上下文
• 步骤 5 中验证通过的 YAML

可选的发现字段： 如果希望课程内容自动呈现，可添加 workflow_phase、tech_stack、lesson_type、impact、keywords。

步骤 7：交叉引用

如果步骤 3 中发现类似问题：

• 在两份文档中添加“相关问题”链接

如果存在 3 个或更多类似问题：

• 考虑将内容添加到 .agents/lessons/patterns/common-solutions.md

如果 severity=critical 且解决方案不明显：

• 在输出中注明：“考虑添加到 Critical Patterns”

输出

记录完成后，调用 fix-decision-router 技能，并提供：

doc_path: .agents/lessons/[category]/[filename].md
category: [problem_type category]

类别映射

problem_type	目录
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/

成功标准

• YAML frontmatter 已通过验证
• 文件已创建在 .agents/lessons/[category]/ 中
• 枚举值与架构完全一致
• 已包含代码示例
• 如果发现相关问题，已添加交叉引用
• 已调用 fix-decision-router

错误处理

错误	操作
缺少上下文	询问用户并等待
YAML 验证失败	显示错误，在通过验证前阻止后续操作
类似问题存在歧义	提供选项，让用户选择

质量指南

应包含：

• 精确的错误消息（直接复制粘贴）
• 文件：行号引用
• 可观察到的症状
• 记录失败的尝试
• 技术原因说明
• 代码示例（修改前/后）
• 预防建议

应避免：

• 模糊的描述
• 缺少技术细节
• 缺少上下文（版本、文件）
• 没有说明的代码转储