do-debug（进行调试）

Do Debug

Language-agnostic systematic debugging method. Four mandatory phases before any fix: Investigation → Pattern analysis → Hypothesis testing → Implementation. Works across any runtime and language.

Trigger boundary

Use this skill when the task is to:

• debug a runtime bug you can reproduce but whose causal mechanism is unknown
• recover from a fix that failed — the symptom persists, regressed, or moved
• investigate an intermittent ("sometimes") failure where pattern-matching a quick fix is tempting
• stop yourself mid-diagnosis when you feel pulled toward "let me just try X"
• audit a multi-layer bug where the obvious layer has been checked but the bug persists

Prefer another skill when:

• a specific diagnostic tool is available and loaded (Chrome DevTools, profiler, language-specific debugger) → use the tool's specific skill if available
• the task is "reason about a design tradeoff" with no bug to reproduce → do-think
• the user explicitly wants a user-in-the-loop brainstorm about architecture → do-think (Mode: Interactive — this skill routes there at the 3-fails gate)
• only "confirm what's actually done" is needed on already-fixed items → check-completion
• the code is not running yet — pure design or scoping work → do-think (Solo or Interactive depending on user presence)
• the bug is an external-service outage the agent cannot inspect → out of scope; surface the fact and stop

Non-negotiable rules

1. Iron Law. No fix before root cause. Fix attempts with unverified mechanism are forbidden.
2. Diagnosis and repair are separate steps. During Phases 1-3, the only edits allowed are *diagnostic* — temporary logs, probes, tests that reproduce the bug, instrumentation. No *fixes* to product logic until Phase 4, after Phase 3 has confirmed a mechanism.
3. Evidence per claim. Every hypothesis cites a trace, log, diff, test run, or config value.
4. One hypothesis at a time. Testing two fixes simultaneously discards the falsification signal of both.
5. Escalate at 3. Three failed fixes triggers the do-think Interactive handoff (see Escalation gate).
6. Verify before declaring fixed. The same symptom reproduction that failed must now pass with evidence captured.
7. Regression-proof before commit. The fix lands with a test, guard, or assertion that proves the mechanism stays dead.
8. Keep the diagnosis trace. Reasoning from Phase 1 → Phase 4 attaches to the fix (commit body, issue comment, or a plan file).

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

An untested fix is a guess dressed as work. A guess that appears to succeed is the worst case — it masks the real mechanism, which returns later as a different symptom.

Required workflow

1. Investigation

Goal: define the exact failing behavior, reproduce it deterministically, capture minimum evidence.

Steps:

1. State the symptom precisely — where (file/line/frame), when (on what input/action), expected vs. actual, first-seen commit or version if known.
2. Reproduce deterministically — the smallest repro that fails 10/10. If intermittent, route to references/bisection-strategies.md input-space bisection before continuing.
3. Capture evidence — stack trace, log excerpt, diff vs. last-known-good, relevant config/env values. Copy-pasteable.
4. Write the symptom card — one paragraph a stranger could read and reproduce the bug without additional context. If you cannot, you are still storytelling, not investigating.

Exit criteria: symptom card + 10/10 repro + copy-pasteable evidence.

Red flags → back to step 1: "it happens sometimes" (repro not 10/10); "some config mismatch" (no concrete values); "the code looks wrong" (guessing, not observing).

2. Pattern analysis

Goal: identify 1-3 candidate mechanisms by matching evidence to known failure patterns.

Steps:

1. Trace backward — apply references/root-cause-tracing.md to walk from the symptom frame back to the earliest frame where state was still correct.
2. Map to pattern families — test-pollution, race condition, silent error-swallowing, serialization boundary, off-by-one, null propagation, config drift, ACL/permission, resource leak.
3. Produce 1-3 candidate mechanisms — each a one-sentence hypothesis of the form *"X caused Y because Z."* Evidence attached.
4. Rank by disprovability — the candidate you can disprove cheapest is tested first.

Exit criteria: 1-3 ranked, evidence-backed candidate mechanisms written down.

Red flags → back to Phase 1: evidence gaps appear (you need a log you don't have); candidates are all "maybe the code is wrong" (pattern not identified); only one candidate is possible (force a second — absence of alternatives is over-commitment).

3. Hypothesis testing

Goal: prove or disprove each candidate with an experiment designed to fail *if the hypothesis is wrong*.

Steps:

1. Design falsifiable experiments — for the top candidate, write down the predicted result if the hypothesis is true AND the predicted result if false. If you cannot state the false-case prediction, the experiment is cover for a pre-decided fix.
2. Run the cheapest experiment first — log addition, print, unit test, bisect step, feature-flag toggle. See references/instrumentation.md and references/bisection-strategies.md.
3. Read the result honestly — even if it invalidates your preferred candidate. Especially then.
4. If all candidates falsified → route to do-think to re-form the space of mechanisms before repeating Phase 2.

Exit criteria: one candidate mechanism confirmed with evidence the experiment produced.

Red flags → back to Phase 2: your "confirmation" also fits a different mechanism (experiment was not falsifying); you changed product code mid-experiment (left Phase 3 early); you accepted a partial confirmation "because it kind of matched."

4. Implementation

Goal: apply the narrowest fix that restores the broken assumption, verify it, land it with a regression guard.

Steps:

1. Write the narrowest fix — one assumption restored, no unrelated cleanup. See references/defense-in-depth.md for *which layer* the fix belongs at.
2. Add the regression guard — a test, assertion, or invariant that fails if the mechanism reappears. Non-optional.
3. Run the Phase 1 repro — the 10/10 failing repro must now be 10/10 passing. Same conditions.
4. Remove temporary diagnosis code — *structural* instrumentation stays; temporary prints come out.
5. Route to check-completion — before declaring done, verify nothing else in scope was broken by the change. See references/integration.md for the handoff format.

Exit criteria: symptom gone (evidence) + regression guard (test/assertion) + check-completion result.

Red flags → back to Phase 3: the repro still fails (hypothesis was wrong, not just the fix); the regression guard passes without the fix (guard doesn't test the mechanism); new symptoms appear (you widened the blast radius).

Integration decision matrix

This skill does not handle everything alone. The matrix below is the first-class routing table — consult it when a phase goes sideways.

Full decision tree with edge cases: references/integration.md.

Escalation gate — the 3-fails rule

A "failed fix" = a hypothesis-driven change that did not make Phase 1's repro pass, OR made it pass but with a regression elsewhere. Compilation errors unrelated to the hypothesis do not count.

• Fail 1 → re-open Phase 2. The pattern family was likely wrong.
• Fail 2 → re-open Phase 1. The symptom definition or repro was probably incomplete.
• Fail 3 → Stop fixing. Route to do-think (Mode: Interactive). Three failures means the problem is architecture-shaped, not a bug. Full handoff format in references/escalation.md and references/integration.md.

The rule is load-bearing under pressure. See references/rationalizations.md for the verbatim excuses agents generate to skip it.

Rationalizations to counter (short form)

Abridged table. Full set + pressure-scenario sidebars in references/rationalizations.md.

Voice discipline (short form)

Debugging-specific forbidden phrases (distinct from check-completion's general voice rules). Full list in references/voice.md.

Forbidden: "probably just a quick fix" / "let me just try" / "I know what this is" (without a named mechanism) / "this feels like last time".

Required forms: "Phase 1 symptom card: …" / "Phase 2 candidates: …" / "Phase 3 falsification prediction: …" / "Verification result: …".

Reference routing

Top-level

Language-specific condition-based-waiting

Pressure scenarios

Output contract

Before declaring a bug fixed, produce these artifacts in order:

1. Symptom card (Phase 1) — one paragraph, reproducible by a stranger
2. Ranked candidate mechanisms (Phase 2) — 1-3 one-sentence hypotheses with evidence
3. Experiment design + result (Phase 3) — falsification prediction + observed result
4. Fix + regression guard (Phase 4) — narrow fix, test/assertion that fails without it
5. Verification (Phase 4) — the Phase 1 repro now passes, evidence captured
6. Next-step pointer — check-completion handoff, or "close and ship"

Each artifact is visible in the session transcript. Do not batch them to the end.

Do this, not that

Guardrails and recovery

• Do not edit product code during Phases 1-3.
• Do not declare "fixed" without a passing Phase 1 repro + regression guard.
• Do not recommend do-debug as the next-step (no infinite regress). If more debugging is needed, state which phase to re-enter.
• Do not skip the 3-fails handoff "just this once." See references/rationalizations.md.
• Do not consume do-think (in either mode) as a substitute for Phase 1. It is a handoff, not a shortcut.

Recovery moves:

• Phase 1 repro not 10/10 → input-space bisection (references/bisection-strategies.md); do not proceed with a flaky repro
• Phase 3 experiment ambiguous → design a distinguishing test; two mechanisms fitting the same evidence means the experiment was not falsifying
• 3 fails hit → hand off to do-think (Mode: Interactive) with the template in references/integration.md; do not retry
• Post-fix regression detected → Phase 1 on the new symptom; do not paper over with a second fix on top of the first

Final checks

Before declaring done, confirm:

• Phase 1 produced a symptom card + 10/10 repro
• Phase 2 produced 1-3 ranked candidates with evidence per row
• Phase 3 experiment stated its false-case prediction before running
• Phase 3 confirmed one mechanism (not "partially matched")
• Phase 4 fix is narrow (no unrelated cleanup, no unrelated files)
• Regression guard exists and fails without the fix
• Phase 1 repro now passes 10/10 with evidence captured
• Diagnosis trace attached to commit body / issue / plan file
• Zero occurrences of forbidden rationalizations in the session output
• Next-step pointer to check-completion (or explicit "close and ship")