foreman-debug

# foreman-debug

(Adapted from obra/superpowers `systematic-debugging` (MIT) — see NOTICE. Made
headless: removed the "discuss with your human partner" hand-offs — under Foreman
there is no live human, so a genuine architectural dead end becomes a FOREMAN-SUMMARY
`escalate` from the surrounding foreman-tdd run, not a question. Folded the regression
step into Foreman's existing `foreman-test` + evidence contract.)

You are invoked **inside a foreman-tdd build session** when something is failing: a
red test that should be green, the project test/lint/typecheck command, the issue's
`acceptance_check`, or a distilled failure report from a prior attempt. You run
**headless** — do not ask questions. Find the root cause, fix it at the source, and
hand control back to foreman-tdd. You emit **no FOREMAN-SUMMARY** of your own; the
foreman-tdd run owns the single summary block.

## The Iron Law

```
NO FIX WITHOUT ROOT-CAUSE INVESTIGATION FIRST
```

A symptom patch that makes the red go away without explaining *why* it was red is a
failure — it will bounce at Foreman's merge gate or resurface on the next slice.

## The four phases (complete each before the next)

### 1. Root cause

- **Read the failure completely.** The exact assertion, the stack trace, the file and
  line, the `ERROR` lines in the `foreman-test` log on disk. The message often *is*
  the answer. If a distilled failure report from a prior attempt is in your context,
  treat its "why it was rejected" as the starting hypothesis, not noise to re-discover.
- **Reproduce deterministically.** Run the single failing test through `foreman-test`
  (use `--fast` while iterating). If it is flaky, that *is* the bug — chase the
  nondeterminism (ordering, time, shared state), don't paper over it.
- **Check what changed.** `git diff` the slice against the integration branch. The
  regression almost always lives in the diff.
- **Trace the bad value to its source.** Where does the wrong value originate? What
  passed it in? Keep walking *up* the call stack until you reach the origin. Fix
  there, not at the symptom.

### 2. Pattern

Find working code that does the same thing elsewhere in the repo. List **every**
difference between it and the broken path, however small — "that can't matter" is how
root causes hide.

### 3. Hypothesis

State one specific hypothesis: "the root cause is X because Y." Make the **smallest**
change that tests it. One variable at a time. If it doesn't hold, form a *new*
hypothesis — do not stack a second fix on top of an unproven first.

### 4. Fix at the source

1. **Lock it with a failing test first.** Add (or keep) a test that fails *because of
   this root cause* and will pass once it's fixed — exactly the red-green discipline
   foreman-tdd already uses. A fix with no test that proves it does not count.
2. **One change.** Address the root cause only — no "while I'm here" refactors.
3. **Verify through `foreman-test`.** The targeted test passes AND the full suite
   stays green. Read the output; do not assume.

## When 3+ fixes have failed

If three distinct fixes each fail or each surfaces a new problem somewhere else, the
issue is **architectural, not a bug** — the slice's seam is wrong. Stop patching.
Hand back to foreman-tdd with a clear note for its FOREMAN-SUMMARY: set `escalate:
true` with a one-line statement of the structural problem (e.g. "ISS-012 assumes a
synchronous store but the queue is async — the seam can't hold"). A wrong architecture
is Foreman's human's call, not another guess.

## Red flags — stop and return to phase 1

- "Quick fix now, understand it later."
- "Just try changing X and see."
- Bundling several changes, then running tests.
- Proposing a fix before you traced the bad value to its origin.
- A fourth fix attempt after three failures (→ escalate the architecture instead).