菜单
Structured debugging when facing bugs, test failures, or unexpected runtime behavior. Follows a phased approach: reproduce → gather info → hypothesize → verify → fix. Use when: diagnosing bugs, failing tests, flaky behavior, or unexplained runtime errors.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Read-only cross-artifact consistency analysis after planning and before approval. Verifies that spec.md, requirements.json, plan.md, tasks/Tn.md, traceability.json are mutually consistent: no duplicate/ambiguous requirements, every behavior mapped to a task, no orphan tasks, no coverage gaps, no contradictions. Outputs artifact-analysis.json with coverage% and severity. CRITICAL/HIGH findings block the approval gate. Use when: planning produced plan.md + tasks + traceability.json, before the user approves the plan.
Explore 2-3 implementation options with trade-offs when the user describes a new feature or requirement. Use when: the user asks for a new feature design, implementation options, or technical trade-off analysis.
After implementation and before final verification, compare current code/tests against the intent inventory (requirements.json + traceability.json). Classify each requirement/behavior as covered, missing, partial, contradicts, or unrequested. Append missing/partial/contradicts as new tasks back to executing. Repeat until converged: zero blocker findings. Outputs convergence-report.json. Use when: executing produced test-report.md but before loom-verification-before-completion.
Expand each requirement into verifiable Behavior Obligations across 15 fixed dimensions (happy-path, boundary, invalid-input, authorization, state-transition, idempotency, concurrency, atomicity, external-failure, compatibility, security, performance, observability, recovery, forbidden-behavior) before planning. Use when: brainstorming produced requirements.json and spec is approved, but behaviors are still placeholders or only happy-path; before loom-writing-plans.
Read-only adversarial reviewer that looks for what SHOULD exist but doesn't, by cross-checking Behavior Obligations against code, tests, expected side effects, forbidden side effects, failure scenarios, and public API changes. Focuses on negative space: events that should not repeat, permissions that should not be bypassed, partial writes that should not happen, old APIs that should not change, swallowed exceptions, leaked secrets. Outputs findings.json. Use when: executing or converge needs an independent omission sweep.
Analyze user request + collect signals (file scope, keywords, worktree state, spec existence), then select pipeline steps via rule short-circuit / AI fallback / rule-based fallback. Select steps first, expose the choice to the user, and persist selected dynamic_steps only after explicit user confirmation; pipeline-plan.md is optional for manual review. Use when: user is unsure which pipeline type to pick, or wants AI to choose steps automatically.
| name | loom-systematic-debugging |
| description | Structured debugging when facing bugs, test failures, or unexpected runtime behavior. Follows a phased approach: reproduce → gather info → hypothesize → verify → fix. Use when: diagnosing bugs, failing tests, flaky behavior, or unexplained runtime errors. |
| when_to_use | Diagnose bugs, failing tests, flaky behavior, or unexplained runtime errors through a structured loop. |
| argument-hint | <failure or symptom> |
| user-invocable | true |
先找根因，再修问题。 系统化方法首次修复率约 95%，随机猜测仅 40%。
Phase 1 完成前不许提出解决方案。 三次修复失败 → 重新审视架构，不是再试一次补丁。
Phase 1 的完成标准不是“看起来知道原因”，而是已经建立一个 red-capable feedback loop：一个已运行过、能暴露失败、足够快、agent 可重复执行的命令、测试、脚本或 harness。
多组件系统：在每个边界插桩，定位数据流在哪里断了。
阶段映射：Step1+2=收集信息 → Step3+4=形成/验证假设 → Step5+6=修复验证
先构造可运行的 pass/fail 信号，再进入根因分析。可选方式包括：
完成标准：
如果无法建立反馈环，必须停止并说明已尝试的方法、缺失的环境/日志/artifact，以及需要用户提供什么；不得进入修复。
错误信息：控制台输出、日志文件、堆栈追踪
上下文信息：触发条件、输入数据、系统状态
对比分析：最近的代码变更、配置变更、环境变更
基于收集的信息，列出 3-5 个按可能性排序、可证伪的原因：
| # | 假设 | 依据 | 验证方法 |
| --- | -------------- | ---------------- | -------------- |
| 1 | 数据库连接超时 | 日志显示连接错误 | 检查连接池配置 |
| 2 | 参数解析错误 | 请求参数格式异常 | 检查绑定标签 |
逐一验证假设，每次只验证一个：
详细模式和工具见 references/common-patterns.md
当调试异步问题时，不要使用固定 sleep，而是：
建立多层防护来验证假设：
出现以下想法意味着你在走捷径，立即回到 Phase 1：
所有这些意味着：停止猜测，回到根因分析。
## 调试报告
**问题描述：** xxx
**影响范围：** xxx
**复现步骤：**
1. xxx
2. xxx
### 根因分析
- **反馈环：** <已运行命令 / 测试 / harness>
- **失败信号：** <red 输出摘要>
- **直接原因：** xxx
- **根本原因：** xxx
### 修复方案
- **修改文件：** path/to/file
- **修改内容：** xxx
- **回归测试：** 已添加测试覆盖
### 预防措施
- 添加监控告警
- 添加单元测试覆盖