Menu
问题排查。当用户遇到编译错误、运行时异常、单测失败、流水线报错、现网告警等需要定位问题时触发。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
代码文件修改的统一入口。当用户请求任何代码变更（新功能、优化、Bug 修复、重构）时必须首先调用此 skill。仅适用于代码文件（如 .cc/.cpp/.h/.go/.py 等），修改 .md 等非代码文件时不需要调用。它会评估复杂度、检查 spec.md、生成 tasks.md、并逐个任务执行。
测试生成。基于 spec.md 或被测代码，生成单元测试、集成测试、性能测试。当用户请求生成测试、TDD 模式、或 workflow-code-generation 完成后触发。
将纠错经验沉淀为持久化的 Rules/Skills 更新，构建反馈闭环。当被用户纠正且错误具有模式性时自动触发，或通过 /reflect 命令手动触发回顾。
代码评审。协调 5 个专项 reviewer subagent 对代码进行并行多维度审查。可由用户直接触发，也可由主 agent 加载后作为 Judge 执行。
需求澄清。只负责明确"要解决什么问题"，生成 spec.md 的前三章节（背景、目标、需求）。禁止在本阶段讨论设计方案——设计是 workflow-system-design skill 的职责。
系统设计。当 spec.md 前三章节（背景、目标、需求）已完整但设计章节为空时调用。按 spec.md 章节顺序逐个与用户讨论，每轮只处理一个 section。
| name | troubleshooting |
| description | 问题排查。当用户遇到编译错误、运行时异常、单测失败、流水线报错、现网告警等需要定位问题时触发。 |
NO ASSUMPTIONS. NO FIX WITHOUT ROOT CAUSE.
禁止在缺少 log 的情况下猜测根因。
当用户提供的 log 不足以定位问题时：
示例：
# 查找某个错误码相关的日志
grep -E "error_code|ErrorCode" /path/to/log | head -50
# 查找某个函数调用前后的上下文
grep -B5 -A10 "FunctionName" /path/to/log
# 按时间范围过滤
grep "2025-01-29 10:3[0-9]" /path/to/log | grep -i error
要点：
流水线/现网问题排查时，创建排查记录文档实时跟踪进度。
判断是否创建：询问用户问题类型：
模板位置：reference/troubleshooting-log-template.md
创建方式：
cp skills/troubleshooting/reference/troubleshooting-log-template.md \
troubleshooting-[问题简述]-$(date +%Y%m%d).md
记录要点：
| 危险想法 | 正确做法 |
|---|---|
| "看起来像是 X" | 有什么证据？让用户验证 |
| "试试改 Y 看看" | 这是猜测，不是诊断 |
| "应该是 Z 导致的" | "应该"不是证据 |
| 必须收集 | 深度排查额外收集 |
|---|---|
| 错误日志、堆栈、错误码 | 时间线、环境差异 |
| 复现条件、触发步骤 | 是否间歇性发生 |
| 代码版本、最近变更 | 完整服务拓扑 |
代码上下文调研（必须）：调用 codebase-researcher subagent 调研问题相关的代码上下文，包括：
信息不足时主动追问，不要猜测。
形成假设 → 让用户验证 → 确认或否定 → 迭代
3+ 轮失败规则：连续 3 轮假设被否定 → 停止猜测，扩大信息收集范围。
流水线/现网问题时，在 reference/cases/ 搜索匹配案例：
symptoms.keywords根据项目需要，可在 reference/ 下为特定模块添加专项排查资料。
复杂/代表性问题排查后，按 case_template.md 沉淀到 reference/cases/<module>/。
| 规则 | 说明 |
|---|---|
| 禁止假设 | 结论必须基于代码 + log，不得凭经验猜测 |
| Iron Law | 未找到根因，禁止提修复建议 |
| 禁止缺 log 猜根因 | log 不足时，从代码中找关键 log 并提供 grep 命令，不得猜测 |
| 代码上下文调研 | 必须调用 codebase-researcher subagent 调研问题相关代码 |
| 实时更新文档 | 每次新进展/新结论必须更新排查记录，同步维护待确认点 |
| 假设验证 | 让用户验证，不脑补结果 |
| 3+ 轮规则 | 连续失败则扩大范围 |