foreman-debug
Headless root-cause debugging loop for a Foreman worker whose tests, build, or acceptance check are failing — especially on a retry. Find the root cause before changing anything, fix at the source with a regression test, and never thrash on symptom patches. Used inside a foreman-tdd build session; emits no summary of its own.
npx skills add VisionForge-OU/foreman --skill foreman-debug --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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 failu
- The Iron Law
- The four phases (complete each before the next)
- 1. Root cause
- 2. Pattern
- 3. Hypothesis
- 4. Fix at the source
- When 3+ fixes have failed
- Red flags — stop and return to phase 1
What does the foreman-debug skill do?
Headless root-cause debugging loop for a Foreman worker whose tests, build, or acceptance check are failing — especially on a retry. Find the root cause before changing anything, fix at the source with a regression test, and never thrash on symptom patches. Used inside a foreman-tdd build session; emits no summary of its own.
How do I install it?
Run `npx skills add VisionForge-OU/foreman --skill foreman-debug --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From VisionForge-OU/foreman, a repository with 421 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.