基于 UAT 的并行缺陷诊断工作流get-shit-done 的 diagnose-issues 全解析【免费下载链接】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导读本文深入解析 get-shit-done 项目中diagnose-issues工作流的完整设计当用户验收测试UAT发现功能缺口gap时它如何编排多个gsd-debugger子代理并行调查根因再将诊断结果回写进 UAT.md交给plan-phase --gaps生成精准修复计划。读完本文你将掌握先诊断、后规划的缺陷闭环方法论以及其中的并行子代理编排、工作树安全守卫、UAT 缺口 YAML 数据结构等可复用的工程细节。文中所有命令、模板与流程均来自当前仓库的实际源码与文档。一、为什么需要诊断前置从症状到根因的鸿沟diagnose-issues工作流位于 get-shit-done/workflows/diagnose-issues.md它的核心原则只有一句话Diagnose before planning fixes.UAT 告诉系统什么坏了症状调试代理负责找出为什么坏根因plan-phase --gaps随后基于真实原因而非猜测创建针对性修复。文档用一组对比例子说明差异方式症状结论后果不做诊断评论不刷新猜一个修复可能修错做诊断评论不刷新useEffect 缺少依赖精确修复从架构视角看这是典型的WHAT 与 WHY 分离设计verify-work工作流负责生产WHAT见 get-shit-done/workflows/verify-work.md 中的diagnose_issues步骤diagnose-issues负责生产WHYplan-phase --gaps负责生产HOW。每一层只做一件事上下文因此保持精简。二、工作流定位它如何融入 GSD 缺陷闭环diagnose-issues不是独立命令而是由verify-work在用户验收发现缺口后自动触发的编排层。在 get-shit-done/workflows/verify-work.md 的diagnose_issues步骤中{N} issues found. Diagnosing root causes... Spawning parallel debug agents to investigate each issue.其流程为加载 diagnose-issues 工作流 → 为每个缺口并行派生调试代理 → 收集根因 → 更新 UAT.md → 交给plan_gap_closure。诊断运行是全自动的无需用户提示并行调查让额外开销最小化同时让修复更准确。闭环的后续环节由 get-shit-done/references/planner-gap-closure.md 定义plan-phase --gaps读取status: diagnosed的 UAT.md将每个缺口truth、reason、artifacts、missing分组为 gap closure 计划最终由 commands/gsd/execute-phase.md 的--gaps-only标志执行。三、编排者的五项职责并行诊断全流程编排者orchestrator保持精简解析缺口、派生代理、收集结果、更新 UAT。完整流程分为五步。3.1 parse_gaps从 UAT.md 提取缺口首先读取 UAT.md 的 Gaps 小节YAML 格式- truth: Comment appears immediately after submission status: failed reason: User reported: works but doesnt show until I refresh the page severity: major test: 2 artifacts: [] missing: []对每个缺口还要读取 Tests 小节中对应的测试以获取完整上下文然后构建缺口列表gaps [ {truth: Comment appears immediately..., severity: major, test_num: 2, reason: ...}, {truth: Reply button positioned correctly..., severity: minor, test_num: 5, reason: ...}, ... ]这一结构的字段含义与 get-shit-done/templates/UAT.md 的模板一致truth是失败测试的预期行为reason是用户原话描述severity由verify-work从用户自然语言推断blocker/major/minor/cosmetictest是测试编号artifacts与missing留待诊断阶段填充。3.2 report_plan向用户报告诊断计划先读取工作树配置USE_WORKTREES$(gsd-sdk query config-get workflow.use_worktrees 2/dev/null || echo true)然后输出诊断计划表## Diagnosing {N} Gaps Spawning parallel debug agents to investigate root causes: | Gap (Truth) | Severity | |-------------|----------| | Comment appears immediately after submission | major | | Reply button positioned correctly | minor | | Delete removes comment | blocker | Each agent will: 1. Create DEBUG-{slug}.md with symptoms pre-filled 2. Investigate autonomously (read code, form hypotheses, test) 3. Return root cause This runs in parallel - all gaps investigated simultaneously.3.3 spawn_agents并行派生调试代理这是整个工作流的技术核心。首先加载子代理技能与基线提交AGENT_SKILLS_DEBUGGER$(gsd-sdk query agent-skills gsd-debugger) EXPECTED_BASE$(git rev-parse HEAD)然后为每个缺口填充debug-subagent-prompt模板并并行派生单条消息内派生全部代理Agent( promptfilled_debug_subagent_prompt \n\nworktree_branch_check\nFIRST ACTION: assert this is a disposable worktree branch before any repair. Run:\nbash\nHEAD_REF$(git symbolic-ref --quiet HEAD || echo \DETACHED\)\nACTUAL_BRANCH$(git rev-parse --abbrev-ref HEAD)\nif [ \$HEAD_REF\ \DETACHED\ ] || echo \$ACTUAL_BRANCH\ | grep -Eq ^(main|master|develop|trunk|release/.*)$; then\n echo \FATAL: diagnose worktree HEAD on $ACTUAL_BRANCH; refusing reset --hard on a protected branch.\ 2\n exit 1\nfi\nif ! echo \$ACTUAL_BRANCH\ | grep -Eq ^worktree-agent-[A-Za-z0-9._/-]$; then\n echo \FATAL: diagnose worktree HEAD $ACTUAL_BRANCH is not in the worktree-agent-* namespace; refusing reset --hard.\ 2\n exit 1\nfi\nACTUAL_BASE$(git merge-base HEAD {EXPECTED_BASE})\nif [ \$ACTUAL_BASE\ ! \{EXPECTED_BASE}\ ]; then\n git reset --hard {EXPECTED_BASE}\n [ \$(git rev-parse HEAD)\ ! \{EXPECTED_BASE}\ ] { echo \ERROR: Could not correct worktree base\; exit 1; }\nfi\n\nFixes EnterWorktree creating branches from main on all platforms while preventing protected-branch data loss.\n/worktree_branch_check\n\nfiles_to_read\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n/files_to_read\n${AGENT_SKILLS_DEBUGGER}, subagent_typegsd-debugger, ${USE_WORKTREES ! false ? isolationworktree, : }, descriptionDebug: {truth_short} )这段派生代码包含三个值得注意的工程细节子代理类型必须使用精确名称gsd-debugger定义见 agents/gsd-debugger.md不能回退到general-purpose。工作树隔离当workflow.use_worktrees未设为false时每个代理在独立 worktree 中运行isolationworktree并行互不干扰。worktree 分支安全检查代理的第一个动作必须是断言自己处于可丢弃的 worktree 分支上才允许reset --hard。检查逻辑包括拒绝在 DETACHED 状态或main|master|develop|trunk|release/*等受保护分支上执行分支名必须匹配^worktree-agent-[A-Za-z0-9._/-]$命名空间基线必须与EXPECTED_BASE一致否则回滚重置。这一守卫同时解决了EnterWorktree 在所有平台上从 main 创建分支和防止受保护分支数据丢失两个问题。此外工作流明确要求在调用 Agent() 派生调试代理后编排者必须立即停止工作不得读取更多文件、编辑代码或运行与这些缺口相关的测试直到所有子代理返回。这一规则防止重复工作、冲突编辑和上下文浪费。模板占位符如下占位符含义{truth}失败了的预期行为{expected}来自 UAT 测试{actual}reason 字段中的用户原话{errors}UAT 中的错误信息或 None reported{reproduction}Test {test_num} in UAT{timeline}Discovered during UAT{goal}find_root_cause_onlyUAT 流程修复交给 plan-phase --gaps{slug}由 truth 生成3.4 collect_results收集根因每个代理返回结构化诊断结果## ROOT CAUSE FOUND **Debug Session:** ${DEBUG_DIR}/{slug}.md **Root Cause:** {specific cause with evidence} **Evidence Summary:** - {key finding 1} - {key finding 2} - {key finding 3} **Files Involved:** - {file1}: {whats wrong} - {file2}: {related issue} **Suggested Fix Direction:** {brief hint for plan-phase --gaps}编排者解析出四个字段root_cause、files、debug_path调试会话文件路径、suggested_fix供缺口闭合计划参考。如果代理返回## INVESTIGATION INCONCLUSIVE则根因记为Investigation inconclusive - manual review needed并保留代理返回的剩余可能性。3.5 update_uat将诊断回写 UAT.md对 Gaps 小节中的每个缺口补充root_cause、artifacts、missing和debug_session字段- truth: Comment appears immediately after submission status: failed reason: User reported: works but doesnt show until I refresh the page severity: major test: 2 root_cause: useEffect in CommentList.tsx missing commentCount dependency artifacts: - path: src/components/CommentList.tsx issue: useEffect missing dependency missing: - Add commentCount to useEffect dependency array - Trigger re-render when new comment added debug_session: .planning/debug/comment-not-refreshing.md随后将 frontmatter 中的 status 更新为diagnosed并提交gsd-sdk query commit docs({phase_num}): add root causes from diagnosis --files .planning/phases/XX-name/{phase_num}-UAT.md注意UAT.md 模板中 Gaps 小节的 YAML 本身预置了root_cause: 、artifacts: []、missing: []、debug_session: 四个待填充字段见 get-shit-done/templates/UAT.mddiagnose-issues 正是这些字段的唯一写入方。完整的测试完成 → 诊断 → 状态推进生命周期同样在该模板的diagnosis_lifecycle小节中有说明。3.6 report_results汇报并移交最后输出诊断完成报告━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► DIAGNOSIS COMPLETE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | Gap (Truth) | Root Cause | Files | |-------------|------------|-------| | Comment appears immediately | useEffect missing dependency | CommentList.tsx | | Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx | | Delete removes comment | API missing auth header | api/comments.ts | Debug sessions: ${DEBUG_DIR}/ Proceeding to plan fixes...随后返回verify-work编排者进行自动规划。工作流强调不要提供手动下一步选项——后续由 verify-work 处理。四、上下文效率设计症状预填与单一职责diagnose-issues的两条上下文效率原则症状预填代理启动时直接从 UAT 拿到symptomsexpected / actual / errors / reproduction / timeline跳过症状收集阶段。对应地gsd-debugger在symptoms_prefilled: true模式下会跳过symptom_gathering直接进入investigation_loop并以status: investigating而非 gathering创建调试文件。只诊断不修复goal: find_root_cause_only模式下调试代理在确认根因后即停止跳过fix_and_verify将根因交还给调用方。这保证了诊断阶段不产生代码变更修复计划的唯一来源是plan-phase --gaps。模板 get-shit-done/templates/debug-subagent-prompt.md 就是两者的载体mode块中同时声明symptoms_prefilled和goal两个字段symptoms块则直接携带 UAT 中的全部症状数据。五、调试代理内部诊断结果为何可信虽然 diagnose-issues 只负责编排但结果的可靠性来自 agents/gsd-debugger.md 的严格方法论理解它有助于评估诊断质量可证伪性要求好的假设必须能被实验推翻。useEffect 缺少依赖 优于状态有问题。单一假设测试一次只改一个变量否则无法归因。结构化推理检查点在任何修复提议之前必须填写五字段reasoning_checkpointhypothesis、confirming_evidence、falsification_test、fix_rationale、blind_spots五个字段填不出具体答案就说明根因尚未确认。调试文件协议.planning/debug/{slug}.md是调试代理的大脑包含 frontmatter 状态、Current Focus、Symptoms不可变、Eliminated只追加、Evidence只追加、Resolution。代理在每次动作之前更新文件保证/clear后可从next_action精确续跑。文件结构详见 get-shit-done/templates/DEBUG.md。知识库协议已解决的会话会追加到.planning/debug/knowledge-base.md新会话在调查起点按关键词重叠2 词匹配既往根因作为假设候选而非确定结论。调试代理的返回值中还有一个Specialist Hint字段根据涉及文件的扩展名和错误模式推断 typescript/react/swift/python/rust/go/ios/android/general它在gsd-debug-session-manageragents/gsd-debug-session-manager.md中会被映射到对应的专家技能做修复评审——这是诊断链路上游机制的一部分在 UAT 诊断find_root_cause_only场景中通常不触发。六、故障处理与成功标准6.1 失败处理策略工作流为三种故障场景预定义了降级路径故障处理方式代理找不到根因将该缺口标记为 needs manual review继续处理其他缺口报告不完整诊断代理超时检查 DEBUG-{slug}.md 的部分进展可用/gsd:debug恢复所有代理均失败通常是系统性问题权限、git 等上报人工调查降级为不带根因的plan-phase --gaps精度较低6.2 成功标准- [ ] Gaps parsed from UAT.md - [ ] Debug agents spawned in parallel - [ ] Root causes collected from all agents - [ ] UAT.md gaps updated with artifacts and missing - [ ] Debug sessions saved to ${DEBUG_DIR}/ - [ ] Hand off to verify-work for automatic planning其中${DEBUG_DIR}为.planning/debug带前导点的隐藏目录所有调试会话文件均保存在此。七、从诊断到修复下游消费链路诊断数据在移交后继续驱动闭环plan-phase --gaps读取 UAT.md 的 Gaps 小节此时含根因。按 get-shit-done/references/planner-gap-closure.md规划器按同一 artifact、同一关注点、依赖顺序将缺口分组为计划每个gap.missing条目转为一个task动作生成带gap_closure: true标记的 PLAN.md。plan-checker 验证verify-work继续派生gsd-plan-checker验证修复计划若发现问题则进入最多 3 轮的 planner ↔ checker 修订循环。execute-phase --gaps-only修复计划就绪后执行 commands/gsd/execute-phase.md 的--gaps-only模式只执行 gap closure 计划。至此UAT 发现问题 → 并行诊断根因 → 基于根因规划修复 → 验证计划 → 定向执行的完整链路闭合每一条修复都建立在实际证据之上而非猜测。八、小结可复用的编排模式diagnose-issues工作流浓缩了一套值得借鉴的 Agent 编排模式WHAT / WHY / HOW 分层验收负责采集症状诊断负责定位根因规划负责生成修复三层职责清晰、上下文各自精简并行与隔离每个缺口一个子代理、一条消息内并行派生、worktree 隔离运行配合分支命名空间守卫保证安全持久化状态调试会话文件让任意代理可在/clear后无缝续跑知识库让既往根因成为新调查的起点结构化契约UAT.md 的 YAML 缺口、子代理的结构化返回、失败降级路径共同构成了机器可解析的协作协议。对任何采用验收驱动开发 多代理协作的工程团队而言这套先诊断、后规划的闭环都是一份高价值的参考实现。【免费下载链接】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），仅供参考 基于 UAT 的并行缺陷诊断工作流：get-shit-done 的 diagnose-issues 全解析
基于 UAT 的并行缺陷诊断工作流get-shit-done 的 diagnose-issues 全解析【免费下载链接】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导读本文深入解析 get-shit-done 项目中diagnose-issues工作流的完整设计当用户验收测试UAT发现功能缺口gap时它如何编排多个gsd-debugger子代理并行调查根因再将诊断结果回写进 UAT.md交给plan-phase --gaps生成精准修复计划。读完本文你将掌握先诊断、后规划的缺陷闭环方法论以及其中的并行子代理编排、工作树安全守卫、UAT 缺口 YAML 数据结构等可复用的工程细节。文中所有命令、模板与流程均来自当前仓库的实际源码与文档。一、为什么需要诊断前置从症状到根因的鸿沟diagnose-issues工作流位于 get-shit-done/workflows/diagnose-issues.md它的核心原则只有一句话Diagnose before planning fixes.UAT 告诉系统什么坏了症状调试代理负责找出为什么坏根因plan-phase --gaps随后基于真实原因而非猜测创建针对性修复。文档用一组对比例子说明差异方式症状结论后果不做诊断评论不刷新猜一个修复可能修错做诊断评论不刷新useEffect 缺少依赖精确修复从架构视角看这是典型的WHAT 与 WHY 分离设计verify-work工作流负责生产WHAT见 get-shit-done/workflows/verify-work.md 中的diagnose_issues步骤diagnose-issues负责生产WHYplan-phase --gaps负责生产HOW。每一层只做一件事上下文因此保持精简。二、工作流定位它如何融入 GSD 缺陷闭环diagnose-issues不是独立命令而是由verify-work在用户验收发现缺口后自动触发的编排层。在 get-shit-done/workflows/verify-work.md 的diagnose_issues步骤中{N} issues found. Diagnosing root causes... Spawning parallel debug agents to investigate each issue.其流程为加载 diagnose-issues 工作流 → 为每个缺口并行派生调试代理 → 收集根因 → 更新 UAT.md → 交给plan_gap_closure。诊断运行是全自动的无需用户提示并行调查让额外开销最小化同时让修复更准确。闭环的后续环节由 get-shit-done/references/planner-gap-closure.md 定义plan-phase --gaps读取status: diagnosed的 UAT.md将每个缺口truth、reason、artifacts、missing分组为 gap closure 计划最终由 commands/gsd/execute-phase.md 的--gaps-only标志执行。三、编排者的五项职责并行诊断全流程编排者orchestrator保持精简解析缺口、派生代理、收集结果、更新 UAT。完整流程分为五步。3.1 parse_gaps从 UAT.md 提取缺口首先读取 UAT.md 的 Gaps 小节YAML 格式- truth: Comment appears immediately after submission status: failed reason: User reported: works but doesnt show until I refresh the page severity: major test: 2 artifacts: [] missing: []对每个缺口还要读取 Tests 小节中对应的测试以获取完整上下文然后构建缺口列表gaps [ {truth: Comment appears immediately..., severity: major, test_num: 2, reason: ...}, {truth: Reply button positioned correctly..., severity: minor, test_num: 5, reason: ...}, ... ]这一结构的字段含义与 get-shit-done/templates/UAT.md 的模板一致truth是失败测试的预期行为reason是用户原话描述severity由verify-work从用户自然语言推断blocker/major/minor/cosmetictest是测试编号artifacts与missing留待诊断阶段填充。3.2 report_plan向用户报告诊断计划先读取工作树配置USE_WORKTREES$(gsd-sdk query config-get workflow.use_worktrees 2/dev/null || echo true)然后输出诊断计划表## Diagnosing {N} Gaps Spawning parallel debug agents to investigate root causes: | Gap (Truth) | Severity | |-------------|----------| | Comment appears immediately after submission | major | | Reply button positioned correctly | minor | | Delete removes comment | blocker | Each agent will: 1. Create DEBUG-{slug}.md with symptoms pre-filled 2. Investigate autonomously (read code, form hypotheses, test) 3. Return root cause This runs in parallel - all gaps investigated simultaneously.3.3 spawn_agents并行派生调试代理这是整个工作流的技术核心。首先加载子代理技能与基线提交AGENT_SKILLS_DEBUGGER$(gsd-sdk query agent-skills gsd-debugger) EXPECTED_BASE$(git rev-parse HEAD)然后为每个缺口填充debug-subagent-prompt模板并并行派生单条消息内派生全部代理Agent( promptfilled_debug_subagent_prompt \n\nworktree_branch_check\nFIRST ACTION: assert this is a disposable worktree branch before any repair. Run:\nbash\nHEAD_REF$(git symbolic-ref --quiet HEAD || echo \DETACHED\)\nACTUAL_BRANCH$(git rev-parse --abbrev-ref HEAD)\nif [ \$HEAD_REF\ \DETACHED\ ] || echo \$ACTUAL_BRANCH\ | grep -Eq ^(main|master|develop|trunk|release/.*)$; then\n echo \FATAL: diagnose worktree HEAD on $ACTUAL_BRANCH; refusing reset --hard on a protected branch.\ 2\n exit 1\nfi\nif ! echo \$ACTUAL_BRANCH\ | grep -Eq ^worktree-agent-[A-Za-z0-9._/-]$; then\n echo \FATAL: diagnose worktree HEAD $ACTUAL_BRANCH is not in the worktree-agent-* namespace; refusing reset --hard.\ 2\n exit 1\nfi\nACTUAL_BASE$(git merge-base HEAD {EXPECTED_BASE})\nif [ \$ACTUAL_BASE\ ! \{EXPECTED_BASE}\ ]; then\n git reset --hard {EXPECTED_BASE}\n [ \$(git rev-parse HEAD)\ ! \{EXPECTED_BASE}\ ] { echo \ERROR: Could not correct worktree base\; exit 1; }\nfi\n\nFixes EnterWorktree creating branches from main on all platforms while preventing protected-branch data loss.\n/worktree_branch_check\n\nfiles_to_read\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n/files_to_read\n${AGENT_SKILLS_DEBUGGER}, subagent_typegsd-debugger, ${USE_WORKTREES ! false ? isolationworktree, : }, descriptionDebug: {truth_short} )这段派生代码包含三个值得注意的工程细节子代理类型必须使用精确名称gsd-debugger定义见 agents/gsd-debugger.md不能回退到general-purpose。工作树隔离当workflow.use_worktrees未设为false时每个代理在独立 worktree 中运行isolationworktree并行互不干扰。worktree 分支安全检查代理的第一个动作必须是断言自己处于可丢弃的 worktree 分支上才允许reset --hard。检查逻辑包括拒绝在 DETACHED 状态或main|master|develop|trunk|release/*等受保护分支上执行分支名必须匹配^worktree-agent-[A-Za-z0-9._/-]$命名空间基线必须与EXPECTED_BASE一致否则回滚重置。这一守卫同时解决了EnterWorktree 在所有平台上从 main 创建分支和防止受保护分支数据丢失两个问题。此外工作流明确要求在调用 Agent() 派生调试代理后编排者必须立即停止工作不得读取更多文件、编辑代码或运行与这些缺口相关的测试直到所有子代理返回。这一规则防止重复工作、冲突编辑和上下文浪费。模板占位符如下占位符含义{truth}失败了的预期行为{expected}来自 UAT 测试{actual}reason 字段中的用户原话{errors}UAT 中的错误信息或 None reported{reproduction}Test {test_num} in UAT{timeline}Discovered during UAT{goal}find_root_cause_onlyUAT 流程修复交给 plan-phase --gaps{slug}由 truth 生成3.4 collect_results收集根因每个代理返回结构化诊断结果## ROOT CAUSE FOUND **Debug Session:** ${DEBUG_DIR}/{slug}.md **Root Cause:** {specific cause with evidence} **Evidence Summary:** - {key finding 1} - {key finding 2} - {key finding 3} **Files Involved:** - {file1}: {whats wrong} - {file2}: {related issue} **Suggested Fix Direction:** {brief hint for plan-phase --gaps}编排者解析出四个字段root_cause、files、debug_path调试会话文件路径、suggested_fix供缺口闭合计划参考。如果代理返回## INVESTIGATION INCONCLUSIVE则根因记为Investigation inconclusive - manual review needed并保留代理返回的剩余可能性。3.5 update_uat将诊断回写 UAT.md对 Gaps 小节中的每个缺口补充root_cause、artifacts、missing和debug_session字段- truth: Comment appears immediately after submission status: failed reason: User reported: works but doesnt show until I refresh the page severity: major test: 2 root_cause: useEffect in CommentList.tsx missing commentCount dependency artifacts: - path: src/components/CommentList.tsx issue: useEffect missing dependency missing: - Add commentCount to useEffect dependency array - Trigger re-render when new comment added debug_session: .planning/debug/comment-not-refreshing.md随后将 frontmatter 中的 status 更新为diagnosed并提交gsd-sdk query commit docs({phase_num}): add root causes from diagnosis --files .planning/phases/XX-name/{phase_num}-UAT.md注意UAT.md 模板中 Gaps 小节的 YAML 本身预置了root_cause: 、artifacts: []、missing: []、debug_session: 四个待填充字段见 get-shit-done/templates/UAT.mddiagnose-issues 正是这些字段的唯一写入方。完整的测试完成 → 诊断 → 状态推进生命周期同样在该模板的diagnosis_lifecycle小节中有说明。3.6 report_results汇报并移交最后输出诊断完成报告━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► DIAGNOSIS COMPLETE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | Gap (Truth) | Root Cause | Files | |-------------|------------|-------| | Comment appears immediately | useEffect missing dependency | CommentList.tsx | | Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx | | Delete removes comment | API missing auth header | api/comments.ts | Debug sessions: ${DEBUG_DIR}/ Proceeding to plan fixes...随后返回verify-work编排者进行自动规划。工作流强调不要提供手动下一步选项——后续由 verify-work 处理。四、上下文效率设计症状预填与单一职责diagnose-issues的两条上下文效率原则症状预填代理启动时直接从 UAT 拿到symptomsexpected / actual / errors / reproduction / timeline跳过症状收集阶段。对应地gsd-debugger在symptoms_prefilled: true模式下会跳过symptom_gathering直接进入investigation_loop并以status: investigating而非 gathering创建调试文件。只诊断不修复goal: find_root_cause_only模式下调试代理在确认根因后即停止跳过fix_and_verify将根因交还给调用方。这保证了诊断阶段不产生代码变更修复计划的唯一来源是plan-phase --gaps。模板 get-shit-done/templates/debug-subagent-prompt.md 就是两者的载体mode块中同时声明symptoms_prefilled和goal两个字段symptoms块则直接携带 UAT 中的全部症状数据。五、调试代理内部诊断结果为何可信虽然 diagnose-issues 只负责编排但结果的可靠性来自 agents/gsd-debugger.md 的严格方法论理解它有助于评估诊断质量可证伪性要求好的假设必须能被实验推翻。useEffect 缺少依赖 优于状态有问题。单一假设测试一次只改一个变量否则无法归因。结构化推理检查点在任何修复提议之前必须填写五字段reasoning_checkpointhypothesis、confirming_evidence、falsification_test、fix_rationale、blind_spots五个字段填不出具体答案就说明根因尚未确认。调试文件协议.planning/debug/{slug}.md是调试代理的大脑包含 frontmatter 状态、Current Focus、Symptoms不可变、Eliminated只追加、Evidence只追加、Resolution。代理在每次动作之前更新文件保证/clear后可从next_action精确续跑。文件结构详见 get-shit-done/templates/DEBUG.md。知识库协议已解决的会话会追加到.planning/debug/knowledge-base.md新会话在调查起点按关键词重叠2 词匹配既往根因作为假设候选而非确定结论。调试代理的返回值中还有一个Specialist Hint字段根据涉及文件的扩展名和错误模式推断 typescript/react/swift/python/rust/go/ios/android/general它在gsd-debug-session-manageragents/gsd-debug-session-manager.md中会被映射到对应的专家技能做修复评审——这是诊断链路上游机制的一部分在 UAT 诊断find_root_cause_only场景中通常不触发。六、故障处理与成功标准6.1 失败处理策略工作流为三种故障场景预定义了降级路径故障处理方式代理找不到根因将该缺口标记为 needs manual review继续处理其他缺口报告不完整诊断代理超时检查 DEBUG-{slug}.md 的部分进展可用/gsd:debug恢复所有代理均失败通常是系统性问题权限、git 等上报人工调查降级为不带根因的plan-phase --gaps精度较低6.2 成功标准- [ ] Gaps parsed from UAT.md - [ ] Debug agents spawned in parallel - [ ] Root causes collected from all agents - [ ] UAT.md gaps updated with artifacts and missing - [ ] Debug sessions saved to ${DEBUG_DIR}/ - [ ] Hand off to verify-work for automatic planning其中${DEBUG_DIR}为.planning/debug带前导点的隐藏目录所有调试会话文件均保存在此。七、从诊断到修复下游消费链路诊断数据在移交后继续驱动闭环plan-phase --gaps读取 UAT.md 的 Gaps 小节此时含根因。按 get-shit-done/references/planner-gap-closure.md规划器按同一 artifact、同一关注点、依赖顺序将缺口分组为计划每个gap.missing条目转为一个task动作生成带gap_closure: true标记的 PLAN.md。plan-checker 验证verify-work继续派生gsd-plan-checker验证修复计划若发现问题则进入最多 3 轮的 planner ↔ checker 修订循环。execute-phase --gaps-only修复计划就绪后执行 commands/gsd/execute-phase.md 的--gaps-only模式只执行 gap closure 计划。至此UAT 发现问题 → 并行诊断根因 → 基于根因规划修复 → 验证计划 → 定向执行的完整链路闭合每一条修复都建立在实际证据之上而非猜测。八、小结可复用的编排模式diagnose-issues工作流浓缩了一套值得借鉴的 Agent 编排模式WHAT / WHY / HOW 分层验收负责采集症状诊断负责定位根因规划负责生成修复三层职责清晰、上下文各自精简并行与隔离每个缺口一个子代理、一条消息内并行派生、worktree 隔离运行配合分支命名空间守卫保证安全持久化状态调试会话文件让任意代理可在/clear后无缝续跑知识库让既往根因成为新调查的起点结构化契约UAT.md 的 YAML 缺口、子代理的结构化返回、失败降级路径共同构成了机器可解析的协作协议。对任何采用验收驱动开发 多代理协作的工程团队而言这套先诊断、后规划的闭环都是一份高价值的参考实现。【免费下载链接】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），仅供参考