cc-investigate
Skill1 starsChanged 7 months agoMITView on GitHub
Use when a bug, regression, broken task, or unexpected behavior needs root-cause investigation, reproducible evidence, and a frozen repair handoff before cc-do resumes coding.
In this repository18 other files it gives its agents.
- life-actSkill
- life-chooseSkill
- life-discoverSkill
- life-integrateSkill
- life-investigateSkill
- life-principleSkill
- life-proveSkill
- life-roadmapSkill
- life-roundtableSkill
- memory-write-gateSkill
- restart-lifeSkill
- cc-actSkill
- cc-checkSkill
- cc-doSkill
- cc-planSkill
- cc-roadmapSkill
- cc-simplifySkill
- cc-spec-initSkill
The file
Files
CC-Investigate
[PROTOCOL]: 变更时同步更新
version、CHANGELOG.md、相关模板/脚本引用,然后检查CLAUDE.md
Role
cc-investigate 是 bug 路径里的 Investigate,也可以理解成 Debug Plan。
它不是直接修 bug 的地方,而是替代原来 bug 场景下那种混在 cc-do 里的临场 planning。它先把症状压成证据,再把证据压成根因,再把根因压成一个可执行的修复 handoff。
一句话:
- 新需求走
cc-plan -> cc-do -> cc-check -> cc-act - 已知需求里的 bug 走
cc-investigate -> cc-do -> cc-check -> cc-act
所以现在仓库里有两条闭环:
PDCAIDCA,如果你更喜欢口语,也可以把它理解成DDCA
Read First
PLAYBOOK.mdCHANGELOG.mdreferences/investigation-contract.mdassets/ANALYSIS_TEMPLATE.mdassets/TASKS_TEMPLATE.mdassets/TASK_MANIFEST_TEMPLATE.json
Use This Skill When
- bug 现象很多,但根因还没冻结
- regression 已出现,不能接受“先补一个试试”
cc-do连续修补失败,怀疑上游根因判断错了- review / verification 指出当前修法只是症状补丁
- 你需要一个专门面向 debug 的可执行 handoff,而不是重开 feature planning
如果问题其实是在问“应该做什么功能”或“范围是否要变”,别硬调试,回 cc-plan。
Quick Start
先判断你面对的是哪一类调查现实:
| 现实状态 | 先走什么路径 |
| 症状真实,但还没有稳定复现 | reproduce-first,先把现象钉死 |
| 明显是 regression | diff-trace,先查最近变化 |
| 症状已知,但修复边界可能扩大范围 | contract-check,先判是否还属于当前 requirement |
| 看起来像 bug,实则是未定义行为或新需求 | 直接 reroute 到 cc-plan |
先说“这是什么类问题”,再说“我要怎么修”。没有分类的 debug,最后都会变成乱打补丁。
Harness Contract
- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause, and write only
planning/analysis.md,planning/tasks.md,planning/task-manifest.json, andchange-meta.json. - Forbidden actions: writing production code, disguising guesses as root cause, or skipping directly from symptoms to repair.
- Required evidence: every root-cause claim must point to reproduction evidence, code facts, recent history, or explicit user confirmation.
- Reroute rule: product/scope changes go to
cc-plan; strategy questions go toroadmap; only confirmed repair handoff goes tocc-do.
Output Model
cc-investigate 只允许产出 4 个主文件:
planning/analysis.md- 现象
- 复现
- 证据链
- 假设表
- 已确认根因
- 修复边界
planning/tasks.md- 只保留真正要执行的修复任务
- 顶部明确 canonical contract 是
planning/analysis.md
planning/task-manifest.json- 机器真相源
- 标记当前任务、依赖、验证命令、调查版本链
change-meta.json- 标记当前 bug 是实现偏离 spec、spec 本身缺失,还是 roadmap 假设错误
- 记录这次修复会如何影响 capability truth
cc-investigate 不写生产代码,不在这里偷跑 cc-do。
Entry Gate
- 先确认当前对象仍然属于一个 requirement,而不是整个项目级故障。
- 先收症状事实:错误、触发条件、影响面、复现路径。
- 先读现有 change 目录里的
planning/design.md/planning/analysis.md/planning/tasks.md/planning/task-manifest.json,不要假设自己是第一位调查者。 - 先读代码、测试、日志、相关 capability spec 和最近提交,再下任何假设。
- 如果复现都不稳定,先不要写根因。
Investigation Loop
- Collect symptom
- 记录用户看见了什么
- 记录预期与实际差异
- 记录复现命令或手动路径
- Trace reality
- 沿着代码路径找触点
- 查最近提交和同类改动
- 找现有测试和断点证据
- 判定偏离的是 capability boundary、invariant,还是只是实现细节
- Form hypotheses
- 只保留 1-3 个可被证伪的假设
- 每个假设都写支持证据和反证
- Test hypotheses
- 用复现、日志、断言、最小探针验证
- 三次假设都失败,就停下重建上下文
- Freeze repair contract
- 根因确认后,写进
planning/analysis.md - 只保留最小修复边界
- 输出
planning/tasks.md+planning/task-manifest.json+change-meta.json
- 根因确认后,写进
- Hand off
- 下一步明确写成
cc-do - 如果 repair contract 越过当前 requirement,就 reroute 到
cc-plan
- 下一步明确写成
Good Output
- 看完第一屏就知道 bug 是什么、怎么复现、为什么会坏
- 根因不是感觉,而是被证据钉死的具体断点
- 修复边界清楚到
cc-do不需要二次调查 planning/tasks.md只包含修复任务,不夹带新需求- 如果应该回
cc-plan,理由写清楚,不假装还能继续 patch
Bundled Resources
- 变更记录:
CHANGELOG.md - 调查契约:
references/investigation-contract.md - 分析模板:
assets/ANALYSIS_TEMPLATE.md - 修复任务模板:
assets/TASKS_TEMPLATE.md - manifest 模板:
assets/TASK_MANIFEST_TEMPLATE.json - 分析骨架:
scripts/bootstrap-analysis.sh
Working Rules
- 没有复现,不准声称找到了根因。
- 没有证据,不准把猜测写成结论。
- 先根因,再修复;先调查,再编码。
planning/tasks.md必须足够让cc-do在脱离当前对话后继续推进。- 如果修复方案已经变成新 feature 设计,停止 debug,回
cc-plan。 - 三次假设失败后,默认说明你的调查入口错了,不准继续硬猜。
- 好的调查不是“找了很多可能性”,而是把错误世界缩成一个可信的 repair contract。
Exit Criteria
planning/analysis.md已冻结症状、复现、证据链、根因和修复边界planning/tasks.md/planning/task-manifest.json可直接交给cc-do- 下一步唯一答案是
cc-do、cc-plan或roadmap
Do Not
- 不在这里写生产代码
- 不拿“可能是”冒充“已经证实”
- 不把新需求伪装成 bug 修复
- 不在根因未明时开始堆 patch
Companion Files
- 深入剧本:
PLAYBOOK.md - 变更记录:
CHANGELOG.md - 调查契约:
references/investigation-contract.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

