# Diagnose Discipline — apt:debug posture loader (6-phase loop)

This appendix loads into `apt:debug`'s reasoning context as a posture
upgrade. The existing apt:debug body has 5 phases (Observe → Hypothesize
→ Checkpoint → Test → Conclude) but its Section 2 "Observe" conflates
symptom-gathering with reproduction. Open question #1 was verified — the
gap is real, the appendix is non-trivial.

This appendix carries the 6-phase Aperant discipline. The skill body
loads it and uses Phase 1 (Reproduce) as a **hard prerequisite** before
advancing from Observe to Hypothesize.

## The 6-phase loop

1. **Reproduce.** Establish a reliable repro loop. Until you can
   trigger the bug at will, no hypothesis is testable — you'd be
   guessing about a moving target. The loop MUST be:
   - Deterministic (same input → same failure)
   - Cheap (under 10 seconds preferred; certainly under 60)
   - Minimal (no irrelevant setup; just enough to fail)

2. **Minimise.** Once you can repro, strip the repro to the smallest
   case. Remove every component that isn't load-bearing for the
   failure. A 200-line repro is a hypothesis space; a 10-line repro is
   a near-confirmed cause.

3. **Hypothesise.** ONLY after minimise: write 3-5 ranked falsifiable
   hypotheses. Each hypothesis must:
   - Predict an observable consequence
   - Be testable by changing ONE variable
   - Be ordered by prior probability + cost-to-test

4. **Instrument.** Add the minimum logging / breakpoint / probe to test
   the highest-ranked hypothesis. Change ONE variable. Re-run the
   minimal repro. Observe.

5. **Fix.** When a hypothesis confirms, write the fix. Run the minimal
   repro again — it must now PASS (no more failure). Run the full test
   suite — no new regressions.

6. **Regression-test.** Write a test that pins the fix. The test must
   fail on the pre-fix code and pass on the fixed code. This is what
   stops the bug from coming back six months later when someone
   refactors.

## The Phase-1 prerequisite (load-bearing)

apt:debug's body enforces this constraint: **you do NOT advance from
Observe to Hypothesize until Phase 1 produces a reliable repro loop**.

If you cannot reproduce reliably:

- Spend the budget on getting the repro working before guessing causes
- Add logging in the production / target environment to gather more
  evidence of the failure trigger
- Ask the user for more context (when does it happen? on what input?
  intermittent or consistent?)

It is better to spend 80% of your debug budget on the repro and 20% on
the fix than to spend 100% guessing at causes. Hypothesis-driven
debugging without a reliable repro is just hope, dressed up as method.

## Distinguishing Phase 1 from apt:debug's existing "Observe"

apt:debug's existing Section 2 collects symptom evidence (error
messages, user reports, environment). That's still valuable — it's the
*input* to Phase 1. But "I read the error and inferred the cause"
DOES NOT count as a repro. The repro is a callable artifact: a
command-line invocation, a test, a script — something the agent can
run on demand to trigger the failure.

## Distinguishing Phase 2 (Minimise) from Phase 3 (Hypothesise)

These are different mental modes. Minimise asks "what's the smallest
thing that still fails?" — a reductive activity. Hypothesise asks
"WHY does it fail?" — an explanatory activity. the discipline
separates them because skipping Phase 2 and going straight from "I can
repro" to "here's why" tends to anchor on the first plausible cause
and miss alternatives.

## Practical consequence for the apt:debug body

When this appendix is loaded, apt:debug's Section 2 (Observe) renames
its "Reproduce" sub-step to **Phase 1 (Reproduce — prerequisite)** and
adds a gate: the skill MUST NOT emit any hypothesis (Section 3) until
DEBUG.md records a `repro_loop_verified: true` field.

The appendix's Phase 2 (Minimise) becomes a new sub-section between
apt:debug's Section 2 (Observe) and Section 3 (Hypothesize). DEBUG.md
gains a `minimised_repro` field.

apt:debug's Sections 3-5 (Hypothesize / Checkpoint / Test / Conclude)
align with Phases 3-6 of this appendix; no structural change there.

## Anti-patterns this discipline prevents

- **Sprint-to-hypothesis.** Agent reads the error, picks the first
  plausible cause, writes a fix, and ships. The bug comes back two
  days later under different inputs.
- **Stack-trace cargo cult.** Agent assumes the line at the top of the
  stack trace IS the bug. Often it's an effect, not a cause.
- **Test the fix, not the bug.** Agent writes a test that proves the
  fix works but doesn't exercise the original buggy condition. The
  regression test is a no-op against the future regression.
- **Logging without minimising.** Agent adds 50 log lines in a 200-line
  repro, then drowns in noise. Minimise first; THEN instrument the
  minimal repro.

Loading this appendix and following its Phase 1 prerequisite cuts most
of these failure modes by structural constraint.
