/spec-debug

name: spec-debug
description: 'Diagnosis loop for bugs and failing behavior. Use for errors, stack traces, regressions, failed tests, issue-tracker bugs, stuck investigations after failed fixes, or asks to debug/fix a bug. Not for executing settled plans or feature work — route those to spec-work.'
argument-hint: "[issue reference, error message, test path, or description of broken behavior]"

Debug and Fix

Find root causes, then fix them. This skill investigates bugs systematically — tracing the full causal chain before proposing a fix — and optionally implements the fix with test-first discipline.

Workflow Contract Summary

• **输入：** 可复现的失败、错误、回归、stack trace、issue 或明确异常行为。
• **输出：** 证据闭合的 causal chain、最小修复、回归验证与结构化 handoff；若未授权修复则只返回诊断。
• **硬出口：** 无法复现且缺 replacement evidence、因果链仍有未验证跳步、target repo/source owner/dirty overlap 未解决，或 required verification 失败时不得声明 root cause/fix complete。
• **权威：** 运行时复现、source、test 与 log 提供事实；LLM 判断因果充分性；诊断、local mutation、commit 与 landing 分别授权。
• **消费者：** 用户、`spec-work`、`spec-code-review`、issue/PR owner 与后续知识沉淀流程。

<bug_description> #<invocation arguments supplied by the current host> </bug_description>

Mode

The default mode is interactive. Investigate, present the causal chain, and use the Phase 2 fix-choice gate and Phase 4 handoff as written below.

When the invocation includes `mode:pipeline-return`, strip that token from `<bug_description>` and load `references/pipeline-return.md`. This mode is for an outer workflow such as `spec-lfg`: it replaces blocking questions with conservative defaults, applies only an inherited and explicitly authorized local convergent fix, and returns a structured envelope to the caller. The mode token does not authorize mutation, commit, push, external communication, credentials, or tracker writes.

Scenario Capability

Follows `docs/contracts/workflows/scenario-capability-matrix.md`. Overrides: high-risk

• `foreign-residual-workspace` -> `blocked-action-required`: stop before fix mutation, root-cause-confirmed claims that depend on suspect local artifacts, commits, or PR-ready handoff until the named cleanup/init action runs or the user explicitly accepts degraded evidence.
• optional external-tool evidence unavailable -> `fallback-only`: continue with bounded direct source, test, log, runtime-probe, and user-provided evidence; disclose the missing capability and do not extend root-cause or blast-radius claims beyond that evidence.
• `non-git-build-workspace` coverage gaps -> `partial`: keep investigation/fixes inside the explicit `target_repo` or inspected build surface and directly inspect uncovered modules before claiming they are unaffected.

Core Principles

1. **Investigate before fixing.** Do not propose a fix until you can explain the full causal chain from trigger to symptom with no gaps. "Somehow X leads to Y" is a gap. 2. **Predictions for uncertain links.** When the causal chain has uncertain or non-obvious links, form a prediction — something in a different code path or scenario that must also be true. If the prediction is wrong but a fix "works," you found a symptom, not the cause. When the chain is obvious (missing import, clear null reference), the chain explanation itself is sufficient. 3. **One change at a time.** Test one hypothesis, change one thing. If you're changing multiple things to "see if it helps," stop — that is shotgun debugging. 4. **When stuck, diagnose why — don't just try harder.**

Anti-Rationalization Red Flags

| 红旗念头 | 停下来做什么 | | --- | --- | | 「我看出 bug 了，跳过复现」 | 先建立最小复现或取得等价捕获证据；没有 red-capable loop 时只能形成 working hypothesis，不能关闭 causal chain gate。 | | 「root cause 很明显」 | 用源码、日志、测试或 runtime value 补齐从 trigger 到 symptom 的 causal chain，不把直觉当 confirmed evidence。 | | 「修完了，手测一下就行」 | 复跑 original reproducer、regression 和适用 broader checks，记录 structured summary；不能只写 freeform “tests passed”。 |

这是注意力提醒,不是 gate,也不替代 LLM 判断;最终是否停下、如何处理仍由你按当前证据决定。

Execution Flow

| Phase | Name | Purpose | |-------|------|---------| | 0 | Triage | Parse input, fetch issue if referenced, proceed to investigation | | 1 | Investigate | Reproduce the bug, trace the code path | | 2 | Root Cause | Form hypotheses with predictions for uncertain links, test them, **causal chain gate**, smart escalation | | 3 | Fix | Only if user chose to fix. Test-first fix with workspace safety checks | | 4 | Handoff | Structured summary, then prompt the user for the next action |

Beyond the trivial-bug fast-path in Phase 0, no further phase skipping — complex bugs simply spend more time in each phase naturally. No further complexity tiers.

---

Phase 0: Triage

Parse the input and reach a clear problem statement.

**Repository and source boundary:** Resolve the current Git root before repo-dependent investigation. In a parent workspace, bounded read-only orientation may compare likely child repos, but require a single `target_repo` or explicit per-fix repo scope before any behavior-bearing test, instrumentation write, or fix. Do not let cwd or broad discovery choose a sibling repo. Canonical checked-in source is the fix owner; generated runtime mirrors under `.claude/`, `.codex/`, `.agents/skills/`, `.cursor/`, `.kiro/`, or `.qoder/` are not source. If runtime drift is causal, repair source/generation first and regenerate only with explicit authorization.

**If the input references an issue tracker**, fetch it:

• GitHub (`#123`, `org/repo#123`, github.com URL): Parse the issue reference from `<bug_description>` and fetch with `gh issue view <number> --json title,body,comments,labels`. For URLs, pass the URL directly to `gh`.
• Other trackers (Linear URL/ID, Jira URL/key, any tracker URL): Attempt to fetch using available MCP tools or by fetching the URL content. If the fetch fails — auth, missing tool, non-public page — ask the user to paste the relevant issue content. Ensure the fetch includes the full comment thread, not just the opening description.

Read the full conversation — the original descript