Foreman Debug Agent Skill

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

• 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.

• One change. Address the root cause only — no "while I'm here" refactors.
• 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).