Debugging Architect

Skill: Debugging Architect — Diagnosis Without the Spiral

Apply Guidelines Skill — load the guidelines-meta skill before proceeding. Profile section owned: §Guardrails → Known blind spots (Guidelines §5). Every root cause that a green pipeline failed to catch gets written there, so the next change is checked against it.

Why this skill exists: debugging is the one activity where an agent reliably makes things worse. The failure mode is not being wrong — it's being wrong repeatedly and confidently, changing five things at once, and leaving a codebase that's harder to reason about than before it started. Every rule below exists to stop that.

Operational Constraints (Strict)

1. Reproduce before you theorise. A bug you cannot reproduce is a bug you cannot verify you fixed. If it can't be reproduced, that is the finding — say so and pivot to §Unreproducible.
2. Change one thing at a time. Each pass alters exactly one variable and predicts the result before running. Two simultaneous changes make a passing result uninterpretable.
3. Hard pass ceiling (Guidelines §16). Three hypotheses tested and disproved → stop. Do not start a fourth. State what's been ruled out, name the assumption most likely wrong, and ask one diagnostic question. This is §17's debug-spiral rule made binding: "still broken" three turns running means the frame is wrong, not that the next guess needs more effort.
4. Never fix by weakening. Deleting an assertion, loosening a tolerance, adding a skip, widening a mock, or wrapping the symptom in a try/catch is not a fix — it is the bug plus concealment (Testing Architect constraint 3).
5. No speculative fixes. "This might help" is not a fix. If you can't state why the change makes the symptom impossible, you haven't found the cause. Changes that "seem to help" without an explanation are the beginning of the spiral, not the end of it.
6. Revert your own probes. Debug logging, temporary instrumentation, and narrowing scaffolds come out before you're done — or are called out explicitly if deliberately kept.
7. Production first, diagnosis second. If users are affected, deployment-architect's Rollback Mode runs first. Restore service, then debug the artifact at leisure. Production is not a debugging environment.
8. Git and golden-file guards are enforced by the plugin's PreToolUse hook (Guidelines §9, §10): every git write, gh publish, --no-verify, and snapshot update is denied by the runtime; read-only inspection stays open. git bisect is a branch-moving operation and is denied like the rest — surface the command for the user, or use a read-only equivalent.

What to Read, and When

The six phases below are the spine and apply to every run. These are read on demand:

Phase 1 — Establish the Symptom

Answer these before touching code. Guessing here costs whole sessions.

Get the real error text. Not a paraphrase — the stack trace, the failing assertion, the actual value. A paraphrased error has already lost the detail that identifies the cause.

Phase 2 — Narrow Before Hypothesising

Resist the first plausible theory. Cut the search space first; a bisected search beats an inspired guess, and it works when you have no intuition at all.

Bisect along whichever axis is cheapest here:

• Time — which commit introduced it? git bisect is the tool; surface the commands, don't run them (§8). A git log over the suspect paths is often enough.
• Code path — does the failure survive when a layer is removed? Call the unit directly, bypass the framework, stub the collaborator.
• Data — does it fail for all inputs or one shape? Empty, boundary, unicode, very large, null, pre-migration rows.
• Environment — local vs. CI vs. deployed. Runtime version, env vars, timezone, locale, filesystem case-sensitivity, network egress.
• Config — does it fail with defaults? A wrong flag is a common and invisible cause.

The layer question, asked early: is this your code, your usage of a dependency, the dependency itself, or the environment? Each has a different fix and a different owner, and mixing them up wastes the most time.

Phase 3 — One Hypothesis at a Time

For each pass, write these three lines before running anything:

Hypothesis: <the specific mechanism you believe causes this>
Prediction:  if true, <this exact observable> will happen
Test:        <the single change or probe that discriminates>

Rules:

• The prediction must be falsifiable. "It'll probably work better" tests nothing. "The value will be undefined at line 42" is a real test.
• A disproved hypothesis is progress — record it. The list of ruled-out causes is the most valuable artifact of a hard debug session, and it's what makes handing over possible.
• Confidence gate (module-findings §2). Before declaring a root cause, self-score: is this proven or merely consistent with the evidence? Below ~80, say so plainly and keep it labelled as a theory. A confidently-stated wrong diagnosis is worse than an honest "not certain yet" — the user acts on it.
• Count the passes. At three disproved hypotheses, stop (§3). Not a suggestion.

Check the known blind spots first — the profile's §Guardrails list, plus implementing-architect's protocols. A startling number of "impossible" bugs are: a stale template binding that type-check can't see, a test double missing a method, a config declared in one environment but not another, or a cache serving a previous build.

Phase 4 — Prove the Cause

Before fixing, close the loop both ways:

1. Explain the whole symptom. A cause that explains most of it is usually adjacent to the real one. Unexplained residue means you're not done.
2. Make it appear and disappear on demand. Toggle the cause; the symptom must follow. That's proof, not correlation.
3. Explain the "why now" — if this code is old, what changed to expose it? Skipping this is how the same bug returns in a different shape.

Phase 5 — Fix It Once

1. Write the failing test first, per the testing-architect skill. It must fail for the right reason — run it before the fix and read the failure. A regression test that would pass without the fix is decoration.
2. Fix the cause, not the symptom. If the honest fix is large, say so and let the user choose between a scoped mitigation (labelled as such, with the real fix as a follow-up) and doing it properly now. Never disguise a mitigation as a fix.
3. Smallest change that removes the cause (Guidelines §2, §3). Do not refactor the surrounding area because you were in there.
4. Check propagation. If the fix touches shared shape, a public API, or an external origin, load the module-propagation skill and run the matching protocol — bug fixes hit the same mirror sites features do, with less scrutiny.
5. Run the gates per the module-gate-battery skill, once as a batch.
6. Remove your probes (§6).

Phase 6 — Make It Impossible to Recur Silently

The step that separates debugging from firefighting. A fix nobody can accidentally undo is worth more than the fix itself.

• The regression test stays. Named for the bug's behaviour, not its ticket.
• If a gate should have caught this and didn't, that is a finding about the gates: write it into the profile's §Guardrails → Known blind spots, in one line, phrased as what to check next time.
• If the class can recur elsewhere, add it to §Recurring Propagation Sites so future changes get swept.
• If it was a production incident, hand the guard to deployment-architect — a pre-flight check is cheaper than a second outage.
• If the root cause was a wrong assumption in a plan, say so; that's feedback for planning-architect, not shame.

Quality Checklist Before Claiming "Fixed"

• Reproduced before diagnosing — or explicitly reported as unreproduced.
• Narrowed before hypothesising; the search was cut, not guessed at.
• Each pass changed one variable with a written, falsifiable prediction.
• Stopped and reassessed at three disproved hypotheses rather than continuing.
• Root cause explains the whole symptom, and toggling it toggles the symptom.
• Failing test written first, and it failed for the right reason.
• Fix addresses the cause; any mitigation is labelled a mitigation.
• Nothing was weakened — no deleted assertion, loosened tolerance, added skip, or swallowed exception.
• Propagation protocol run if the fix touched shared shape, a public API, or an origin.
• Debug probes removed.
• Blind spot written to the profile if a gate should have caught this.
• Confidence stated honestly; an unproven cause is labelled unproven.
• No git add, commit, push, or bisect — commands surfaced for the user.

v1.0 — version history in CHANGELOG.md