# Habits Root Cause

> Use when a failure's cause is unproven, before any fix - red test, build or auth error, stack trace, flaky run. Not for a known error code, which catalogs hold.

- Skill: `envoydev/habits-root-cause` (Agent Skill)
- Install (CLI): `npx get-skill add envoydev/habits-root-cause`
- Raw SKILL.md: https://api.skillmd.com/api/skills/envoydev/habits-root-cause/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: envoydev (https://skillmd.com/u/envoydev)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/envoydev/habits-root-cause

---


# Root cause - one hypothesis, one change, then the fix

A fix aimed at a symptom moves the failure somewhere nobody is looking. It finds the cause and says where the fix belongs; who writes the fix is the caller's scope. The loop runs on the obvious one-liner and under time pressure too - a simple bug is one fast pass, not a skipped one.

## When to use

- Fires BEFORE the first fix is written, for: a red test, a build or compile error, an auth or connection failure (a 401 / 403, a rejected token), a stack trace, an exception, a crash, a flaky or intermittent failure, a regression, wrong output, 'it worked yesterday' - and again when a fix did not hold.
- The debugging method that proves the cause before any change is made to fix it.
- Not for what a known failure signature or error code usually means, which the signature catalogs cover, or a whole investigation from scattered evidence (logs, monitors, a customer report), which is the gated diagnose flow's job.

## The loop

1. **Read the whole failure.** Every line of the error, every frame, and the FIRST failure in the log rather than the last - later ones are often fallout. Quote the lines that matter before touching anything; a warning printed beside the error is evidence too.
2. **Make it fail on demand.** One command that shows it red every time. An intermittent failure is a cause not yet isolated: gather the inputs, the timing and the environment delta until it reproduces, or work from the evidence and say that it did not.
3. **Localize - walk back from where it threw.** The top frame is where the bad value landed, rarely where it was made. Follow it upstream across each boundary it crossed (a call, a process, a config load, a serialization) and check what actually crossed. Ask what changed: the diff, the last commits, a bumped dependency, the machine. In a single chat a probe settles which boundary: log what enters and leaves each one, run once, read it, then remove the probe.
4. **Compare with a case that works.** A sibling path in the same code, a passing test, the last green commit. List every difference, small ones included - that list is where the hypotheses come from.
5. **One hypothesis, one change.** Write it as one line in your reply BEFORE the change - 'X fails because Y' - then make the smallest change or check that confirms or kills it, re-run, and read the result before the next. A cause worked out silently and stated only in the close is not a hypothesis - it is the fix explaining itself afterwards. Two changes at once prove nothing. A killed hypothesis is progress: revert its change before the next one, and note it so it is not tried twice.
6. **Fix at the root, test first.** Where writing tests is in scope, a test that fails for the reason you found lands first. Then ONE fix for the cause - never a guard around the symptom, never a bundle of 'while I am here' edits - then the repro and the relevant suite, output quoted, per `habits-done-gate`. The repro still red after the fix means the hypothesis was wrong: revert the fix and go back to step 3.
7. **Three fixes that did not hold: stop.** Three fixes that left the repro red, or that each surfaced a failure somewhere else, mean the shape is wrong, not the line. Put the design question to whoever owns the design - in a chat, ONE AskUserQuestion with the redesign recommended; a seat returns it in its report - instead of forcing a fourth fix. Each option names the measured quantity it changes, and what it claims about it ('memory stays bounded') agrees with the runs so far.

   ```ask
   Three fixes left <the repro> red. Redesign <the part> or try a fourth fix?
   - 'Redesign <the part> (Recommended)' - <the measured quantity it changes, and what it claims about it>
   - 'One more fix at <the line>' - <what it changes; why the three before it did not hold>
   ```

No root cause in the code - the evidence points at the environment, timing or an outside service: say what was ruled out, then handle it where it surfaces (a retry, a timeout, a clear error) and add a log point that catches it next time.

## Where a seat's scope cuts the loop

- A read-only run - a diagnoser seat, or the gated diagnose flow in this chat - runs steps 1-5, adds no instrumentation to the code and writes no fix: it reports the cause, the evidence and the route.
- A repair seat that does not write new tests (a build or test-suite resolver) runs steps 1-5, the one fix of step 6 without its failing test, and step 7.
- A single-chat run takes all seven.

## Signs the loop was skipped

Go back to step 1 on any of these:

- A change made to 'see what happens', with no hypothesis written down.
- A second change before the first one's result was read.
- A fix proposed before the failure reproduces or the evidence isolates it.
- 'It works now', with no sentence saying why.
- A test weakened, skipped or re-baselined to turn the run green.

