Skip to content

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

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.

Say a test fails after a recent change and you do not know why.

  1. You paste the failure.

    The Debug command typed in a shop project, followed by the Debug flow screen: seven stages from BUG to REPORT, with the root-cause and failing-test stages marked

    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.

  2. superlite runs the test and watches it fail.

    Claude Code · ~/shop
    FAILED tests/test_login.py::test_login_after_timeout - assert 401 == 200

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

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

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

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

  6. A fixer changes the code.

    Claude Code · ~/shop
    tier 1 (cause known, one module): Sonnet fixer changes the expiry check

    The 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).

  7. You read the report.

    superlite report
    cause token expiry stored in local time, checked as UTC
    fix the expiry check in auth compares in UTC
    test test_expiry_is_compared_in_utc fails before, passes after
    suite green

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

  • 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 finish marks 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”.