Debug flow
DEBUG ------------------------------------------------------------------------------ [1 BUG] v [2 REPRODUCE] v [3 ROOT CAUSE] v [4 FAILING TEST] v [5 FIX] v [6 VERIFY] v [7 REPORT] ------------------------------------------------------------------------------ 1 BUG You describe what fails and how to see it. 2 REPRODUCE Run it and watch it fail. 3 ROOT CAUSE Find the cause before touching code. 4 TEST A regression test that fails for that cause. 5 FIX By how well the cause is understood: tier 1 known, one module: Sonnet tier 2 spans modules or a seam: Sonnet high tier 3 cause unknown: Opus 6 VERIFY The new test passes and the whole suite is green. 7 REPORT The cause, the fix and the test. No widening of scope. ------------------------------------------------------------------------------How it works
Section titled “How it works”A fix without a known cause is a guess, and guesses create new bugs. So the flow has two rules. The cause comes first, and the test comes before the fix.
Reproduce, then trace. superlite runs the failure and reads the full error, not the first line. It then checks what changed recently, follows a bad value back to where it starts, and states one cause in one sentence: “X is wrong because Y”. For example: “the token expiry is wrong because it is stored in local time”. It tests that sentence with the smallest probe it can think of, one change at a time.
A test that fails for that cause. The regression test is written before the fix, so you can see it fail for the right reason. It then passes after the fix.
Fixes go to agents by tier. The tier says how well the cause is understood, and it picks the agent. Tier 1 (known, one module) goes to Sonnet. Tier 2 (spans modules or a seam) goes to Sonnet high. Tier 3 (cause unknown) goes to Opus. Reviews and fixes uses the same tiers, and parallel build explains the agents.
Verify. The new test passes and the suite is green. The report states the cause, the fix, the test and the evidence. If the cause was never found, it says so instead of shipping a guess.
Example: a login test that fails
Section titled “Example: a login test that fails”Say a test fails after a recent change and you do not know why.
-
You paste the failure.

Real output: the command and the screen printed the moment you start.
superlite prints the stored screen above and opens a session, so the fix lands on its own branch.
-
superlite runs the test and watches it fail.
Claude Code · ~/shop FAILED tests/test_login.py::test_login_after_timeout - assert 401 == 200It reads the whole error, not the first line, and checks what changed recently. A bug it cannot reproduce is a bug it cannot prove fixed, so this comes first.
-
You answer one batch of questions. They are asked only because something material is open.
Claude Code · ~/shop What is the correct behavior after a timeout?What must not change?How far may the fix reach?❯ A session that expires should log in again. Keep the token format. Touch auth only.You decide: the scope. These answers fence the fix in, so it cannot widen into a refactor. The batch also carries the question “Run the whole test suite at finish?”, which defaults to no.
-
superlite states the cause.
Claude Code · ~/shop Root cause: the token is stored with a local-time expiry and checked as UTC.It follows the bad value back to where it starts and tests the sentence with the smallest probe it can think of. This line is the part to read first. It tells you whether the fix addresses the bug or only hides it.
-
A test is written that fails for that cause.
tests/test_login.py def test_expiry_is_compared_in_utc():token = make_token(expires_local="2026-11-12 09:00")assert not is_expired(token, now_utc="2026-11-12 08:30")The test comes before the fix, so you see it fail for the right reason, and it stays as a guard against the bug returning.
-
A fixer changes the code.
Claude Code · ~/shop tier 1 (cause known, one module): Sonnet fixer changes the expiry checkThe cause is known and sits in one module, so it is tier 1. After two failed rounds at a tier, the work moves up one (reviews and fixes).
-
You read the report.
superlite report cause token expiry stored in local time, checked as UTCfix the expiry check in auth compares in UTCtest test_expiry_is_compared_in_utc fails before, passes aftersuite greenThe new test passes and the whole suite is green. The report carries the evidence, so you can judge the fix without rerunning anything.
What you end up with: a small diff in auth, a regression test and a stated cause, uncommitted on the session branch. If the cause is never found, the report says so instead of shipping a guess.
Good to know
Section titled “Good to know”- Obvious failures skip the ceremony. A typo, a missing import or a stack trace that points at the bad line is fixed directly and the focused test re-run.
- After two failed fixes superlite stops and re-reads the evidence from scratch. After three it changes approach. It asks you, or hands the problem to a fresh agent on a stronger model with the repro and the failed attempts. Three failures in different places often signal an architectural problem.
- The questions round only runs when something material is open. It includes “Run the whole test suite at finish?”, and the answer defaults to no: affected tests only.
- At the end,
superlite-cli finishmarks the session finished. The fix stays uncommitted in your folder. - Prefer a plain request? Say it, and superlite suggests Debug from words like “fails” and “broken”.