SuperAPI AI 工具集

kiro-debug

编程与开发

查看项目

更新于 10-16 11:32

技能介绍

用途

kiro-debug 是一个用于根因优先调试的技能。它面向全新上下文的根因调查,结合本地证据、运行时/配置检查,以及在可用时的外部文档或问题研究。它不是用于猜测式调试的补丁生成器。

当出现以下情况时使用本技能:

  • 实施者报告 BLOCKED
  • 审查驳回在补救后重复出现
  • 验证意外失败
  • 任务似乎与运行时或平台现实冲突
  • 同一失败在多次尝试修复后仍然存在

不要在收集证据之前推测修复方案。

主要能力

该技能通过系统化流程进行根因调查,并输出结构化调试报告。其方法包括:

  1. 仔细阅读错误:提取确切的错误文本、堆栈跟踪或失败位置、产生失败的命令,以及失败是确定性的还是间歇性的。
  2. 检查本地运行时与仓库状态:检查 package.json、pyproject.toml、go.mod、Makefile、README*、构建配置、tsconfig 或等效语言/运行时配置、运行时特定配置、依赖版本与脚本,以及来自 git diff 的相关变更文件。
  3. 在可用时搜索网络:搜索确切的错误消息、技术加症状组合、官方文档、版本特定问题跟踪器或迁移说明。优先使用官方文档、官方仓库/问题、版本特定参考、运行时特定文档。
  4. 对根因进行分类:使用以下类别之一——MISSING_DEPENDENCY、RUNTIME_MISMATCH、MODULE_FORMAT、NATIVE_ABI、CONFIG_GAP、LOGIC_ERROR、TASK_ORDERING_PROBLEM、TASK_DECOMPOSITION_PROBLEM、SPEC_CONFLICT、EXTERNAL_DEPENDENCY。
  5. 确定最小的安全下一步动作:判断问题是否可以通过编辑文件、调整配置、添加或更正依赖、重构代码在仓库内修复。当问题在当前已批准任务计划内可通过仓库修复时,使用 NEXT_ACTION: RETRY_TASK。
  6. 判断任务计划是否仍然有效:判断当前已批准的任务计划是否仍可安全地按原样执行。当缺少的前置任务应先存在、当前任务相对于未完成工作的排序不正确、当前任务边界错误且应拆分或合并、任务过大或含糊而无法在当前实现循环内安全修复时,优先使用 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。
  • 关于收费、价格、平台支持范围等信息暂未提供。

常见借口与事实

借口 事实
“这可能只需要快速打个补丁” 补丁优先的调试会造成返工。
“我们试几个修复吧” 多重修复猜测会掩盖根因。
“规格可能是错的,我来适配它” 规格冲突必须被明确浮现出来。
“文档搜索是可选的” 对于运行时/依赖问题,文档和版本问题通常包含通往根因的最短路径。