DEBUG SESSION COMPLETE【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-doneSession:{final path — resolved/ if archived, otherwise debug_file_path}Root Cause:{one sentence from Resolution.root_cause, or not determined}Fix:{one sentence from Resolution.fix, or not applied}Cycles:{N} (investigation) {M} (fix)TDD:{yes/no}Specialist review:{specialist_hint used, or none}若会话因用户选择而放弃则额外标注 **Status:** ABANDONED — session saved for /gsd:debug continue {slug}。 ## 七、会话文件协议.planning/debug/{slug}.md 的完整结构 调试会话的持久化载体是 .planning/debug/{slug}.md其完整模板位于 [get-shit-done/templates/DEBUG.md](https://link.gitcode.com/i/dd39801909802ae65384eca710e3bdd2)。文件结构如下 markdown --- status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved trigger: [verbatim user input] created: [ISO timestamp] updated: [ISO timestamp] --- ## Current Focus !-- OVERWRITE on each update - always reflects NOW -- hypothesis: [current theory being tested] test: [how testing it] expecting: [what result means if true/false] next_action: [immediate next step — be specific, not continue investigating] reasoning_checkpoint: null !-- populated before every fix attempt -- tdd_checkpoint: null !-- populated when tdd_mode is active after root cause confirmed -- ## Symptoms !-- Written during gathering, then immutable -- expected: [what should happen] actual: [what actually happens] errors: [error messages if any] reproduction: [how to trigger] started: [when it broke / always broken] ## Eliminated !-- APPEND only - prevents re-investigating after /clear -- - hypothesis: [theory that was wrong] evidence: [what disproved it] timestamp: [when eliminated] ## Evidence !-- APPEND only - facts discovered during investigation -- - timestamp: [when found] checked: [what was examined] found: [what was observed] implication: [what this means] ## Resolution !-- OVERWRITE as understanding evolves -- root_cause: [empty until found] fix: [empty until applied] verification: [empty until verified] files_changed: []7.1 各区块的更新规则区块规则时机Frontmatter.statusOVERWRITE每个阶段转换Frontmatter.updatedOVERWRITE每次文件更新Current FocusOVERWRITE每次行动前SymptomsIMMUTABLE收集完成后EliminatedAPPEND假设被证伪时EvidenceAPPEND每个发现之后ResolutionOVERWRITE理解演进时最关键的纪律是「先更新文件、后采取行动」——如果行动中途上下文被清空文件仍能显示「即将发生什么」。next_action必须具体可执行糟糕的例子是「continue investigating」「look at the code」好的例子是「Add logging at line 47 of auth.js to observe token value before jwt.verify()」「Run test suite with NODE_ENVproduction to check env-specific behavior」。7.2 状态机与恢复行为gathering - investigating - fixing - verifying - awaiting_human_verify - resolved ^ | | | |____________|___________|_________________| (if verification fails or user reports issue)恢复行为跨 /clear的黄金法则解析 frontmatter 得知状态 → 读 Current Focus 得知正在做什么 → 读 Eliminated 知道不要重试什么→ 读 Evidence 知道已学到什么→ 从next_action继续。正如调试文件协议所言The file IS the debugging brain文件就是调试的大脑。模板同时给出体积约束Evidence 条目 1-2 行、只写事实Eliminated 简洁记录假设失败原因禁止叙述性散文。若证据超过 10 条仍未收敛应检查是否在绕圈子。reasoning_checkpoint与tdd_checkpoint两个字段的存在与语义由测试 tests/debug-session-management.test.cjs 显式断言该测试同时验证list/status/continue子命令逻辑存在于 get-shit-done/workflows/debug.md 中说明会话文件协议是作为稳定契约被维护的。八、调试代理的方法论科学方法的内核虽然会话文件与工作流负责「状态路由」真正的调试智慧来自gsd-debugger代理agents/gsd-debugger.md。它把科学方法拆解为可执行的纪律8.1 可证伪性要求好的假设必须能被证明是错的不可证伪差「状态哪里不对」「时序有问题」「某处有竞态条件」可证伪好「路由变化导致组件重挂载从而重置了用户状态」「API 调用在卸载后完成导致对已卸载组件更新状态」区别在于具体性好的假设做出具体、可测试的断言。8.2 假设测试循环精确观察——不是「坏了」而是「点击一次计数显示 3应为 1」穷举可能原因——列出所有候选先不评判逐个具体化——不是「状态错了」而是「handleClick 被调用了两次导致状态更新两次」确定证据——什么能支持/反驳每个假设。每个假设的实验设计框架包含 7 步预测 → 测试设置 → 测量 → 成功标准 → 执行 → 观察 → 结论。一次只测一个假设——同时改三个东西然后成功了你根本不知道是哪个修好的。8.3 九大调查技术与选型表场景技术大型代码库、文件众多二分搜索Binary Search困惑于发生了什么橡皮鸭调试、可观测性优先复杂系统、多交互最小复现Minimal Reproduction已知期望输出反向推导Working Backwards以前能用、现在不行差分调试、Git Bisect可能原因众多注释掉一切、二分搜索变量构造的路径/URL/键追踪间接引用Follow the Indirection任何修复之前可观测性优先Observability First其中「追踪间接引用」尤其值得注意当代码用变量拼接路径、URL 或键时绝不能想当然——必须分别追踪「生产者writer/installer」与「消费者reader/checker」两端确认两边解析出的实际值一致。典型案例如安装器写入~/.claude/get-shit-done/hooks/而检查器读取~/.claude/hooks/目录不匹配导致「hook 陈旧」误报。8.4 证据质量分级强证据可直接观察、可重复、无歧义、独立如「日志里确实看到 X 发生」「每次做 Y 都失败」「值肯定是 null 而非 undefined」「全新浏览器无缓存也会发生」弱证据道听途说、不可重复、含糊、混淆变量如「我记得好像失败过一次」「重启清缓存升级包之后好了」——无法归因。8.5 结构化推理检查点reasoning_checkpoint在提出任何修复之前强制、不可跳过必须把五字段推理检查点写入 Current Focusreasoning_checkpoint: hypothesis: [exact statement — X causes Y because Z] confirming_evidence: - [specific evidence item 1 that supports this hypothesis] - [specific evidence item 2] falsification_test: [what specific observation would prove this hypothesis wrong] fix_rationale: [why the proposed fix addresses the root cause — not just the symptom] blind_spots: [what you havent tested that could invalidate this hypothesis]如果五个字段无法用具体答案填满说明根因尚未确认必须回到调查循环。这个检查点同时充当橡皮鸭——往往在阐述过程中自己就发现了推理漏洞。8.6 验证纪律什么才算「已修复」一次修复被认定为已验证必须同时满足原始问题不再出现用相同复现步骤验证你能解释修复为什么生效机制而非「改了 X 就好了」相关功能仍正常回归测试通过修复跨环境有效修复稳定多次运行零失败。金律如果无法复现 bug就无法验证它被修复。修复后还应执行稳定性测试如循环运行 100 次、并发/竞态测试随机延迟 1000 次。「看起来能工作」「我觉得修好了」是红旗短语「验证 50 次零失败」「全部测试通过含新增回归测试」才是可信的表达。8.7 研究 vs 推理的平衡该研究外部知识不认识的错误信息、库/框架行为与预期不符、领域知识缺口、平台差异、生态近期变更该推理你自己的代码bug 在你写的代码里、信息完备、纯逻辑错误、答案在行为而非文档中。调查陷阱是「读了几小时文档却没看代码」推理陷阱是「看了几小时代码而答案早已有文档」。二者应交替进行、各有明确问题。九、知识库沉淀让过去的根因成为未来的假设调试代理维护一个追加式知识库.planning/debug/knowledge-base.md每次成功解析的会话追加一条记录## {slug} — {one-line description of the bug} - **Date:** {ISO date} - **Error patterns:** {comma-separated keywords from Symptoms.errors Symptoms.actual} - **Root cause:** {Resolution.root_cause} - **Fix:** {Resolution.fix} - **Files changed:** {Resolution.files_changed joined as comma list} ---匹配逻辑基于关键词重叠大小写不敏感2 词重叠即候选而非语义相似。新会话调查循环的 Phase 0 会先读知识库若命中则把匹配结果作为known_pattern_candidate记入 Current Focus优先测试该假设——但只把它当作一个假设而非既定诊断。知识库的写入时机在archive_session之后即用户确认修复后。十、归档与提交会话如何走向终点调试代理的archive_session步骤规定仅在用户通过 human-verify 检查点确认修复端到端生效后mkdir -p .planning/debug/resolved mv .planning/debug/{slug}.md .planning/debug/resolved/随后提交代码绝不使用git add -A或git add .只精确添加修改的文件并通过 SDK 提交规划文档自动尊重commit_docs配置git add src/path/to/fixed-file.ts git commit -m fix: {brief description} Root cause: {root_cause} gsd-sdk query commit docs: resolve debug {slug} --files .planning/debug/resolved/{slug}.md【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DEBUG SESSION COMPLETE
DEBUG SESSION COMPLETE【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-doneSession:{final path — resolved/ if archived, otherwise debug_file_path}Root Cause:{one sentence from Resolution.root_cause, or not determined}Fix:{one sentence from Resolution.fix, or not applied}Cycles:{N} (investigation) {M} (fix)TDD:{yes/no}Specialist review:{specialist_hint used, or none}若会话因用户选择而放弃则额外标注 **Status:** ABANDONED — session saved for /gsd:debug continue {slug}。 ## 七、会话文件协议.planning/debug/{slug}.md 的完整结构 调试会话的持久化载体是 .planning/debug/{slug}.md其完整模板位于 [get-shit-done/templates/DEBUG.md](https://link.gitcode.com/i/dd39801909802ae65384eca710e3bdd2)。文件结构如下 markdown --- status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved trigger: [verbatim user input] created: [ISO timestamp] updated: [ISO timestamp] --- ## Current Focus !-- OVERWRITE on each update - always reflects NOW -- hypothesis: [current theory being tested] test: [how testing it] expecting: [what result means if true/false] next_action: [immediate next step — be specific, not continue investigating] reasoning_checkpoint: null !-- populated before every fix attempt -- tdd_checkpoint: null !-- populated when tdd_mode is active after root cause confirmed -- ## Symptoms !-- Written during gathering, then immutable -- expected: [what should happen] actual: [what actually happens] errors: [error messages if any] reproduction: [how to trigger] started: [when it broke / always broken] ## Eliminated !-- APPEND only - prevents re-investigating after /clear -- - hypothesis: [theory that was wrong] evidence: [what disproved it] timestamp: [when eliminated] ## Evidence !-- APPEND only - facts discovered during investigation -- - timestamp: [when found] checked: [what was examined] found: [what was observed] implication: [what this means] ## Resolution !-- OVERWRITE as understanding evolves -- root_cause: [empty until found] fix: [empty until applied] verification: [empty until verified] files_changed: []7.1 各区块的更新规则区块规则时机Frontmatter.statusOVERWRITE每个阶段转换Frontmatter.updatedOVERWRITE每次文件更新Current FocusOVERWRITE每次行动前SymptomsIMMUTABLE收集完成后EliminatedAPPEND假设被证伪时EvidenceAPPEND每个发现之后ResolutionOVERWRITE理解演进时最关键的纪律是「先更新文件、后采取行动」——如果行动中途上下文被清空文件仍能显示「即将发生什么」。next_action必须具体可执行糟糕的例子是「continue investigating」「look at the code」好的例子是「Add logging at line 47 of auth.js to observe token value before jwt.verify()」「Run test suite with NODE_ENVproduction to check env-specific behavior」。7.2 状态机与恢复行为gathering - investigating - fixing - verifying - awaiting_human_verify - resolved ^ | | | |____________|___________|_________________| (if verification fails or user reports issue)恢复行为跨 /clear的黄金法则解析 frontmatter 得知状态 → 读 Current Focus 得知正在做什么 → 读 Eliminated 知道不要重试什么→ 读 Evidence 知道已学到什么→ 从next_action继续。正如调试文件协议所言The file IS the debugging brain文件就是调试的大脑。模板同时给出体积约束Evidence 条目 1-2 行、只写事实Eliminated 简洁记录假设失败原因禁止叙述性散文。若证据超过 10 条仍未收敛应检查是否在绕圈子。reasoning_checkpoint与tdd_checkpoint两个字段的存在与语义由测试 tests/debug-session-management.test.cjs 显式断言该测试同时验证list/status/continue子命令逻辑存在于 get-shit-done/workflows/debug.md 中说明会话文件协议是作为稳定契约被维护的。八、调试代理的方法论科学方法的内核虽然会话文件与工作流负责「状态路由」真正的调试智慧来自gsd-debugger代理agents/gsd-debugger.md。它把科学方法拆解为可执行的纪律8.1 可证伪性要求好的假设必须能被证明是错的不可证伪差「状态哪里不对」「时序有问题」「某处有竞态条件」可证伪好「路由变化导致组件重挂载从而重置了用户状态」「API 调用在卸载后完成导致对已卸载组件更新状态」区别在于具体性好的假设做出具体、可测试的断言。8.2 假设测试循环精确观察——不是「坏了」而是「点击一次计数显示 3应为 1」穷举可能原因——列出所有候选先不评判逐个具体化——不是「状态错了」而是「handleClick 被调用了两次导致状态更新两次」确定证据——什么能支持/反驳每个假设。每个假设的实验设计框架包含 7 步预测 → 测试设置 → 测量 → 成功标准 → 执行 → 观察 → 结论。一次只测一个假设——同时改三个东西然后成功了你根本不知道是哪个修好的。8.3 九大调查技术与选型表场景技术大型代码库、文件众多二分搜索Binary Search困惑于发生了什么橡皮鸭调试、可观测性优先复杂系统、多交互最小复现Minimal Reproduction已知期望输出反向推导Working Backwards以前能用、现在不行差分调试、Git Bisect可能原因众多注释掉一切、二分搜索变量构造的路径/URL/键追踪间接引用Follow the Indirection任何修复之前可观测性优先Observability First其中「追踪间接引用」尤其值得注意当代码用变量拼接路径、URL 或键时绝不能想当然——必须分别追踪「生产者writer/installer」与「消费者reader/checker」两端确认两边解析出的实际值一致。典型案例如安装器写入~/.claude/get-shit-done/hooks/而检查器读取~/.claude/hooks/目录不匹配导致「hook 陈旧」误报。8.4 证据质量分级强证据可直接观察、可重复、无歧义、独立如「日志里确实看到 X 发生」「每次做 Y 都失败」「值肯定是 null 而非 undefined」「全新浏览器无缓存也会发生」弱证据道听途说、不可重复、含糊、混淆变量如「我记得好像失败过一次」「重启清缓存升级包之后好了」——无法归因。8.5 结构化推理检查点reasoning_checkpoint在提出任何修复之前强制、不可跳过必须把五字段推理检查点写入 Current Focusreasoning_checkpoint: hypothesis: [exact statement — X causes Y because Z] confirming_evidence: - [specific evidence item 1 that supports this hypothesis] - [specific evidence item 2] falsification_test: [what specific observation would prove this hypothesis wrong] fix_rationale: [why the proposed fix addresses the root cause — not just the symptom] blind_spots: [what you havent tested that could invalidate this hypothesis]如果五个字段无法用具体答案填满说明根因尚未确认必须回到调查循环。这个检查点同时充当橡皮鸭——往往在阐述过程中自己就发现了推理漏洞。8.6 验证纪律什么才算「已修复」一次修复被认定为已验证必须同时满足原始问题不再出现用相同复现步骤验证你能解释修复为什么生效机制而非「改了 X 就好了」相关功能仍正常回归测试通过修复跨环境有效修复稳定多次运行零失败。金律如果无法复现 bug就无法验证它被修复。修复后还应执行稳定性测试如循环运行 100 次、并发/竞态测试随机延迟 1000 次。「看起来能工作」「我觉得修好了」是红旗短语「验证 50 次零失败」「全部测试通过含新增回归测试」才是可信的表达。8.7 研究 vs 推理的平衡该研究外部知识不认识的错误信息、库/框架行为与预期不符、领域知识缺口、平台差异、生态近期变更该推理你自己的代码bug 在你写的代码里、信息完备、纯逻辑错误、答案在行为而非文档中。调查陷阱是「读了几小时文档却没看代码」推理陷阱是「看了几小时代码而答案早已有文档」。二者应交替进行、各有明确问题。九、知识库沉淀让过去的根因成为未来的假设调试代理维护一个追加式知识库.planning/debug/knowledge-base.md每次成功解析的会话追加一条记录## {slug} — {one-line description of the bug} - **Date:** {ISO date} - **Error patterns:** {comma-separated keywords from Symptoms.errors Symptoms.actual} - **Root cause:** {Resolution.root_cause} - **Fix:** {Resolution.fix} - **Files changed:** {Resolution.files_changed joined as comma list} ---匹配逻辑基于关键词重叠大小写不敏感2 词重叠即候选而非语义相似。新会话调查循环的 Phase 0 会先读知识库若命中则把匹配结果作为known_pattern_candidate记入 Current Focus优先测试该假设——但只把它当作一个假设而非既定诊断。知识库的写入时机在archive_session之后即用户确认修复后。十、归档与提交会话如何走向终点调试代理的archive_session步骤规定仅在用户通过 human-verify 检查点确认修复端到端生效后mkdir -p .planning/debug/resolved mv .planning/debug/{slug}.md .planning/debug/resolved/随后提交代码绝不使用git add -A或git add .只精确添加修改的文件并通过 SDK 提交规划文档自动尊重commit_docs配置git add src/path/to/fixed-file.ts git commit -m fix: {brief description} Root cause: {root_cause} gsd-sdk query commit docs: resolve debug {slug} --files .planning/debug/resolved/{slug}.md【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考