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:

Agent	quality	balanced	budget
kata-debugger	opus	sonnet	sonnet

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”。

模型查找表：

代理名称	quality	balanced	budget
kata-debugger	opus	sonnet	sonnet

存储解析后的模型，供后续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:

Expected behavior - What should happen?
Actual behavior - What happens instead?
Error messages - Any errors? (paste or describe)
Timeline - When did this start? Ever worked?
Reproduction - How do you trigger it?

After all gathered, confirm ready to investigate.

针对以下每项使用AskUserQuestion：

预期行为 - 应该发生什么？
实际行为 - 实际发生了什么？
错误信息 - 是否有错误？（粘贴或描述）
时间线 - 问题何时开始出现？之前正常工作过吗？
复现步骤 - 如何触发该问题？

收集完成后，确认已准备好开始调查。

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>