debug

name	debug
description	Use on any bug, test failure, or unexpected behaviour BEFORE proposing a fix — runs the generic evidence-first root-cause loop.

harness/debug

Native sentropic debugging. Open it with harness debug "<symptom>" (records a WorkEvent), then run the loop. No fix is proposed before the root cause is proven by evidence.

The loop

1. Reproduce — a deterministic, minimal repro. If you can't reproduce it, you can't fix it.
2. Evidence — gather facts with the tools, never assume: make logs-<service>, make db-query QUERY="…", container state (make ps), grep/diff. Read the actual error, the actual state.
3. One hypothesis — the single most-likely cause that the evidence supports. Write it down.
4. One fix — the smallest change that addresses THAT cause. No shotgun edits, no "while I'm here".
5. Re-observe — rerun the repro. Confirm the symptom is gone AND the evidence changed as predicted.
6. Regression test — promote the repro into a test (harness/test) so it can't silently return.

Rules

• No "probably" / "maybe" / "should be" — verify with a tool before asserting. A claim without evidence is a guess.
• Change ONE thing at a time; if the symptom persists, revert it before trying the next.
• A failing assertion is data, not noise — read the diff, don't loosen the assertion.
• Live surfaces (UI/stream/API/extension) have a dev-lane bootstrap (Playwright/probe targets); use it to observe the real behaviour rather than reasoning in the abstract.

Done

Root cause named + evidenced, minimal fix in place, repro green as a regression test, no collateral change. Hand verification to harness verify.