diagnose

Diagnose

从 bug 出发，通过排查代码库来定位根本原因，然后编写详尽的 agent brief 报告，引导 AFK agent 完成修正。把你自己当成一位在代码库中搜索线索的侦探。

流程

1. 获取上下文

读取 issue 对应的票。读取项目根目录下的 CONTEXT.md（如果存在，让 /setup-matt-pocock-skills 确认），理解项目架构、领域术语以及任何相关的 docs/adr/ 下的 ADR。

2. 阅读源代码

追溯 bug —— 从用户看到的行为开始，追踪代码路径，直到找到根源。目标是对应到一个具体的高层级模块以及其中出错的逻辑。具体来说：

• 从 issue 报告的症状出发
• 沿着调用路径往回追溯
• 找出哪段逻辑产生了错误行为
• 如果需要，运行测试和代码检查来验证你的判断
• 查看 git log，找到最近对相关区域所做的修改（git log --oneline --all -- <path>），并把线索一并纳入结论中

3. 编写报告

就以下内容撰写一份有实质内容的报告：

• 发现（为什么出现问题）
• 原因（代码中的根本原因是什么）
• 修复（应该如何改正）

引用具体的函数名、类型和领域术语，但不要写文件路径或行号——这些容易过时。

然后用这份报告去更新 issue（以评论的形式），并附上一份完整的 agent brief，以便 AFK agent 可以接手修正。

指导原则

做代码侦探，而不只是复述者

不要仅仅复述 issue 报告的内容。trace code，形成你自己的判断，然后给出观点。你应该能够说出："我跟着调用链走了一遍，以下是发生了什么、原因是什么、以及需要怎么改。"

引述具体的领域术语

如果项目的 CONTEXT.md 将某个模块称为 "resolver chain"，那你也用这个词。使用代码库自身的词汇体系，能让 agent 更容易根据你的判断采取行动。

写一份其他人能直接拿来用的 agent brief

你的报告只是铺垫，重要的是 agent brief——一个 AFK agent 应该能够严格依据 brief 来完成修复，而不需要再去翻阅 issue 讨论里的上下文。具体格式见 AGENT-BRIEF.md。