用途
kiro-debug 是一个用于根因优先调试的技能。它面向全新上下文的根因调查,结合本地证据、运行时/配置检查,以及在可用时的外部文档或问题研究。它不是用于猜测式调试的补丁生成器。
当出现以下情况时使用本技能:
- 实施者报告 BLOCKED
- 审查驳回在补救后重复出现
- 验证意外失败
- 任务似乎与运行时或平台现实冲突
- 同一失败在多次尝试修复后仍然存在
不要在收集证据之前推测修复方案。
主要能力
该技能通过系统化流程进行根因调查,并输出结构化调试报告。其方法包括:
- 仔细阅读错误:提取确切的错误文本、堆栈跟踪或失败位置、产生失败的命令,以及失败是确定性的还是间歇性的。
- 检查本地运行时与仓库状态:检查 package.json、pyproject.toml、go.mod、Makefile、README*、构建配置、tsconfig 或等效语言/运行时配置、运行时特定配置、依赖版本与脚本,以及来自 git diff 的相关变更文件。
- 在可用时搜索网络:搜索确切的错误消息、技术加症状组合、官方文档、版本特定问题跟踪器或迁移说明。优先使用官方文档、官方仓库/问题、版本特定参考、运行时特定文档。
- 对根因进行分类:使用以下类别之一——MISSING_DEPENDENCY、RUNTIME_MISMATCH、MODULE_FORMAT、NATIVE_ABI、CONFIG_GAP、LOGIC_ERROR、TASK_ORDERING_PROBLEM、TASK_DECOMPOSITION_PROBLEM、SPEC_CONFLICT、EXTERNAL_DEPENDENCY。
- 确定最小的安全下一步动作:判断问题是否可以通过编辑文件、调整配置、添加或更正依赖、重构代码在仓库内修复。当问题在当前已批准任务计划内可通过仓库修复时,使用 NEXT_ACTION: RETRY_TASK。
- 判断任务计划是否仍然有效:判断当前已批准的任务计划是否仍可安全地按原样执行。当缺少的前置任务应先存在、当前任务相对于未完成工作的排序不正确、当前任务边界错误且应拆分或合并、任务过大或含糊而无法在当前实现循环内安全修复时,优先使用 NEXT_ACTION: STOP_FOR_HUMAN。仅当当前任务应停止但队列其余部分仍可安全继续时,使用 NEXT_ACTION: BLOCK_TASK。
使用方式
输入
需要提供:
- 确切的失败症状或阻塞陈述
- 错误消息、堆栈跟踪和失败命令输出
- 当前 git diff 或未提交失败变更的摘要
- 任务简报:正在构建什么
- 审查反馈(如果失败来自审查驳回)
- 相关规格文件路径(requirements.md、design.md)
- 相关需求/设计章节编号
- 相关 ## Implementation Notes
- 已已知的运行时或环境约束
输出
返回:
- ROOT_CAUSE
- CATEGORY
- FIX_PLAN
- VERIFICATION
- NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN
- CONFIDENCE: HIGH | MEDIUM | LOW
- NOTES
使用 spec.json 中指定的语言。
输出格式
## Debug Report
- ROOT_CAUSE: <1-2 sentence root cause>
- CATEGORY: MISSING_DEPENDENCY | RUNTIME_MISMATCH | MODULE_FORMAT | NATIVE_ABI | CONFIG_GAP | LOGIC_ERROR | TASK_ORDERING_PROBLEM | TASK_DECOMPOSITION_PROBLEM | SPEC_CONFLICT | EXTERNAL_DEPENDENCY
- FIX_PLAN:
1. <specific repo-fixable action>
2. <specific repo-fixable action>
- VERIFICATION: <command(s) to confirm the fix>
- NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN
- CONFIDENCE: HIGH | MEDIUM | LOW
- NOTES: <context the next implementer should know>
适用场景
- 实施者报告被阻塞时的根因调查
- 验证失败且原因不明时的系统化排查
- 审查驳回重复出现时的深度分析
- 任务与运行时或平台现实冲突时的诊断
- 同一失败在多次修复尝试后仍然存在时的根因定位
限制
- 该技能不用于在收集证据之前推测修复方案。
- 不要提出多重修复并行的散弹式计划。应先确定根因,然后生成最小的可行修复计划。
- 如果真正的问题是规格冲突或架构问题,应直接说明。
- 不要将暴力代码修复作为修订 tasks.md 或已批准计划的替代方案。
- 如果问题可在当前任务计划内通过仓库变更修复,不要过早升级。
- 当阻塞确实需要人工产品/需求决策、外部凭证或无法访问的服务、硬件或不可用的外部系统、因规格/平台冲突而重新确定范围时,使用 NEXT_ACTION: STOP_FOR_HUMAN。
- 关于收费、价格、平台支持范围等信息暂未提供。
常见借口与事实
| 借口 | 事实 |
|---|---|
| “这可能只需要快速打个补丁” | 补丁优先的调试会造成返工。 |
| “我们试几个修复吧” | 多重修复猜测会掩盖根因。 |
| “规格可能是错的,我来适配它” | 规格冲突必须被明确浮现出来。 |
| “文档搜索是可选的” | 对于运行时/依赖问题,文档和版本问题通常包含通往根因的最短路径。 |