Back to Details

kata-debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> Debug issues using scientific method with subagent isolation.
Orchestrator role: Gather symptoms, spawn kata-debugger agent, handle checkpoints, spawn continuations.
Why subagent: Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction. </objective>
<context> User's issue: $ARGUMENTS
Check for active sessions:
bash
find .planning/debug -maxdepth 1 -name "*.md" 2>/dev/null | grep -v resolved | head -5
</context> <process>
<objective> 采用科学方法并通过子代理隔离来调试问题。
编排器角色： 收集症状信息，生成kata-debugger代理，处理检查点，生成续接代理。
使用子代理的原因： 调查过程会快速消耗上下文（读取文件、形成假设、测试）。每次调查都有全新的20万字符上下文。主上下文保持精简，用于与用户交互。 </objective>
<context> 用户问题：$ARGUMENTS
检查活跃会话：
bash
find .planning/debug -maxdepth 1 -name "*.md" 2>/dev/null | grep -v resolved | head -5
</context> <process>

0. Resolve Model Profile

0. 解析模型配置文件

Read model profile for agent spawning:
bash
MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
Default to "balanced" if not set.
Model lookup table:
Agentqualitybalancedbudget
kata-debuggeropussonnetsonnet
Store resolved model for use in Task calls below.
读取用于生成代理的模型配置文件：
bash
MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
若未设置则默认使用“balanced”。
模型查找表：
代理名称qualitybalancedbudget
kata-debuggeropussonnetsonnet
存储解析后的模型，供后续Task调用使用。

1. Check Active Sessions

1. 检查活跃会话

If active sessions exist AND no $ARGUMENTS:
  • List sessions with status, hypothesis, next action
  • User picks number to resume OR describes new issue
If $ARGUMENTS provided OR user describes new issue:
  • Continue to symptom gathering
若存在活跃会话且未提供$ARGUMENTS：
  • 列出会话的状态、假设和下一步操作
  • 用户选择编号恢复会话或描述新问题
若已提供$ARGUMENTS或用户描述了新问题：
  • 继续收集症状信息

2. Gather Symptoms (if new issue)

2. 收集症状信息（若为新问题）

Use AskUserQuestion for each:
  1. Expected behavior - What should happen?
  2. Actual behavior - What happens instead?
  3. Error messages - Any errors? (paste or describe)
  4. Timeline - When did this start? Ever worked?
  5. Reproduction - How do you trigger it?
After all gathered, confirm ready to investigate.
针对以下每项使用AskUserQuestion：
  1. 预期行为 - 应该发生什么？
  2. 实际行为 - 实际发生了什么？
  3. 错误信息 - 是否有错误？（粘贴或描述）
  4. 时间线 - 问题何时开始出现？之前正常工作过吗？
  5. 复现步骤 - 如何触发该问题？
收集完成后，确认已准备好开始调查。

3. Read Instruction Files

3. 读取指令文件

Before spawning agents, read agent instructions using the Read tool:
  • references/debugger-instructions.md
    (relative to skill base directory) — store as 
    debugger_instructions_content
生成代理前，使用Read工具读取代理指令：
  • references/debugger-instructions.md
    （相对于技能基础目录）—— 存储为
    debugger_instructions_content

4. Spawn Debugger Agent

4. 生成调试器代理

Fill prompt and spawn:
markdown
<objective>
Investigate issue: {slug}

**Summary:** {trigger}
</objective>

<symptoms>
expected: {expected}
actual: {actual}
errors: {errors}
reproduction: {reproduction}
timeline: {timeline}
</symptoms>

<mode>
symptoms_prefilled: true
goal: find_and_fix
</mode>

<debug_file>
Create: .planning/debug/{slug}.md
</debug_file>
Task(
  prompt="<agent-instructions>\n{debugger_instructions_content}\n</agent-instructions>\n\n" + filled_prompt,
  subagent_type="general-purpose",
  model="{debugger_model}",
  description="Debug {slug}"
)
填充提示词并生成代理：
markdown
<objective>
调查问题：{slug}

**摘要：** {trigger}
</objective>

<symptoms>
expected: {expected}
actual: {actual}
errors: {errors}
reproduction: {reproduction}
timeline: {timeline}
</symptoms>

<mode>
symptoms_prefilled: true
goal: find_and_fix
</mode>

<debug_file>
Create: .planning/debug/{slug}.md
</debug_file>
Task(
  prompt="<agent-instructions>\n{debugger_instructions_content}\n</agent-instructions>\n\n" + filled_prompt,
  subagent_type="general-purpose",
  model="{debugger_model}",
  description="Debug {slug}"
)

5. Handle Agent Return

5. 处理代理返回结果

If 
## ROOT CAUSE FOUND
:
  • Display root cause and evidence summary
  • Offer options:
    • "Fix now" - spawn fix subagent
    • "Plan fix" - suggest /kata-plan-phase --gaps
    • "Manual fix" - done
If 
## CHECKPOINT REACHED
:
  • Present checkpoint details to user
  • Get user response
  • Spawn continuation agent (see step 5)
If 
## INVESTIGATION INCONCLUSIVE
:
  • Show what was checked and eliminated
  • Offer options:
    • "Continue investigating" - spawn new agent with additional context
    • "Manual investigation" - done
    • "Add more context" - gather more symptoms, spawn again
若返回
## ROOT CAUSE FOUND
：
  • 显示根本原因和证据摘要
  • 提供选项：
    • "立即修复" - 生成修复子代理
    • "规划修复方案" - 建议使用/kata-plan-phase --gaps
    • "手动修复" - 结束流程
若返回
## CHECKPOINT REACHED
：
  • 向用户展示检查点详情
  • 获取用户回复
  • 生成续接代理（见步骤5）
若返回
## INVESTIGATION INCONCLUSIVE
：
  • 展示已检查和排除的内容
  • 提供选项：
    • "继续调查" - 生成带有额外上下文的新代理
    • "手动调查" - 结束流程
    • "添加更多上下文" - 收集更多症状信息后重新生成代理

6. Spawn Continuation Agent (After Checkpoint)

6. 生成续接代理（检查点之后）

When user responds to checkpoint, spawn fresh agent:
markdown
<objective>
Continue debugging {slug}. Evidence is in the debug file.
</objective>

<prior_state>
Debug file: @.planning/debug/{slug}.md
</prior_state>

<checkpoint_response>
**Type:** {checkpoint_type}
**Response:** {user_response}
</checkpoint_response>

<mode>
goal: find_and_fix
</mode>
Task(
  prompt="<agent-instructions>\n{debugger_instructions_content}\n</agent-instructions>\n\n" + continuation_prompt,
  subagent_type="general-purpose",
  model="{debugger_model}",
  description="Continue debug {slug}"
)
</process>
<success_criteria>
  • Active sessions checked
  • Symptoms gathered (if new)
  • kata-debugger spawned with context
  • Checkpoints handled correctly
  • Root cause confirmed before fixing </success_criteria>
当用户回复检查点信息后，生成全新代理：
markdown
<objective>
继续调试{slug}。证据存储在调试文件中。
</objective>

<prior_state>
Debug file: @.planning/debug/{slug}.md
</prior_state>

<checkpoint_response>
**Type:** {checkpoint_type}
**Response:** {user_response}
</checkpoint_response>

<mode>
goal: find_and_fix
</mode>
Task(
  prompt="<agent-instructions>\n{debugger_instructions_content}\n</agent-instructions>\n\n" + continuation_prompt,
  subagent_type="general-purpose",
  model="{debugger_model}",
  description="Continue debug {slug}"
)
</process>
<success_criteria>
  • 已检查活跃会话
  • 已收集症状信息（若为新问题）
  • 已生成带有上下文的kata-debugger代理
  • 已正确处理检查点
  • 修复前已确认根本原因 </success_criteria>