chore(debug): fold in two techniques, delete systematic-debugging
CI / Check / Test (push) Successful in 1s
CI / Tag release (push) Successful in 1s

superpowers-systematic-debugging restated debug's core (hypothesis before fix)
across 296 lines, with a fix-implementation phase that belongs to tdd and a
rationalization table that mostly repeats debug's own Anti-Patterns. Two things
in it were not restatement, and both are now in debug: instrument every
component boundary before hypothesising when a bug spans components, and treat
three failed fixes as evidence the mechanism was never identified rather than
as a reason to try a fourth.

Not deleted with it, contrary to the issue: find-polluter.sh and the three
technique files (root-cause-tracing, defense-in-depth, condition-based-waiting)
are real assets, one of them an actual tool. They move to debug/references/ with
a stated load trigger each, because a reference nobody knows when to open is
dead weight. The pressure-test transcripts and CREATION-LOG from the upstream
fork go; they document obra's process, not ours.

Pressure-tested per #19, and the RED phase refuted the issue's premise. Two
subagents without the skill got the multi-component scenario and the four-failed-
fixes scenario; both already instrumented boundaries unprompted, and the second
refused to write a fifth fix on its own initiative. So these sections are not
correcting a demonstrated gap in this model — they are insurance for weaker
models and for prompts less well-posed than a test scenario. Recorded as such
rather than claimed as a fix.

The GREEN run applied both sections correctly and then found four defects in
them, all fixed here: the boundary rule read as suspending Iron Law 2's 3-5
hypotheses; the trigger said "reduced" when fixes that change nothing are the
stronger signal; "stop proposing a fourth" read as licence to return no
hypotheses at all; and the references had no load triggers. Its remaining
findings are pre-existing and filed as #36.

41 skills. debug 146 -> 188 lines.

Closes #14
Bump-Type: minor
This commit is contained in:
2026-08-29 11:33:36 +02:00
parent 84a012cd0f
commit 08c935ba8a
13 changed files with 39 additions and 628 deletions
+39
View File
@@ -31,6 +31,33 @@ Debugging is hypothesis generation, not fix generation. The first instinct — "
2. **Generate 3-5 hypotheses, ordered by likelihood (most likely first).** Fewer than 3 means you stopped thinking; more than 5 means you are not prioritizing.
3. **Diagnose only — do not fix in this skill.** The fix happens in a separate TDD cycle (load `tdd` skill) once a hypothesis is confirmed.
## When the bug spans components
A system with boundaries (CI → build → signing, API → service → database) hides the
question "which component is wrong?" behind the question "why is the output wrong?".
Specify, as a pre-step, what to log entering and leaving **each** boundary, plus
whether config and environment actually propagated. One run of that narrows the search
to a single component.
This does not suspend Iron Law 2. Still emit 3-5 hypotheses — the boundary spec comes
first in the output, and each hypothesis says which boundary observation would kill it.
What the pre-step forbids is hypotheses that quietly assume a component is the faulty
one before any evidence says so.
## When several fixes have already failed
Three or more plausible fixes that failed to eliminate a symptom is not a run of bad
luck — it is evidence that nobody has identified the mechanism. (Fixes that changed
nothing at all count double: they are stronger evidence of a misidentified mechanism
than fixes that partially worked.) Each one has been narrowing a window rather than
closing it, and a fourth guess buys another tenth of the rate plus a layer of
interacting guards nobody can reason about.
Say that explicitly — the refusal is the finding, not a preamble to it. Then aim the
hypotheses one level up: the premise those fixes share is itself the thing to falsify.
This is not an exemption from the output format. It is the format, pointed at the
assumption instead of at the symptom.
## Process
### Step 1: Read the failure
@@ -147,3 +174,15 @@ This skill produces high-volume mechanical output (hypothesis enumeration) and i
- After a hypothesis is confirmed, load `tdd` skill — write a failing regression test that proves the bug exists, then fix it.
- For test failures specifically caused by mock-vs-real divergence, also load `tdd/references/testing-anti-patterns.md`.
- Load `code-review` skill if the diagnosis surfaces a structural issue (god object, shotgun surgery) rather than a pointwise bug.
Techniques kept in `debug/references/`, inherited from the deleted
`superpowers-systematic-debugging` (#14):
- `root-cause-tracing.md` — load when the failure surfaces far from its trigger and the
stack is the only thread back to it.
- `defense-in-depth.md` — load after a root cause is confirmed, to decide which layers
should have caught it.
- `condition-based-waiting.md` — load whenever a timeout appears anywhere in the report,
including as one of the fixes already tried. A bumped timeout is a symptom.
- `find-polluter.sh` — run when a test passes alone and fails in the suite, or when
something in the tree appears that no test admits to creating.