diagnose

/supergraph:diagnose

Systematic debugging. Never guess and patch — build a feedback loop, prove the hypothesis, fix once.

Announce: "🐛 /supergraph:diagnose — building feedback loop..."

Setup

Read .supergraph-env for test/lint commands (if exists):

[ -f .supergraph-env ] && source .supergraph-env

This sets $TEST_CMD, $FOCUSED_TEST_CMD, $LINT_CMD. If absent, detect from project config (package.json → jest/vitest, pubspec.yaml → flutter test, etc.) same as /supergraph:scan.

Phases

Phase 1 — Build Feedback Loop

Before touching any code, establish a fast, deterministic way to observe the bug.

# Identify the smallest command that shows the failure
$TEST_CMD --grep "<failing test name>"   # focused test run
# or
<minimal repro command>

Goal: failure visible in < 5 seconds. If not, slim down the repro. Do NOT skip this phase. Debugging without a feedback loop is guessing.

Phase 2 — Reproduce Cleanly

• Run the feedback loop 3 times — confirm it fails consistently
• Capture exact error output, stack trace, exit code
• Note any flakiness → treat as separate bug before continuing
• Add a failing regression test if one doesn't exist:

  test("<bug description>", () => { ... }) // RED
  

Phase 3 — Hypothesize (3-5 ranked theories)

List falsifiable hypotheses, ordered most-to-least likely:

1. [Most likely] — [reason] — [how to falsify]
2. [Second]      — [reason] — [how to falsify]
3. [Third]       — [reason] — [how to falsify]

Rules:

• Each hypothesis must be falsifiable (observable test to disprove it)
• No implementation yet — only theories
• Use graph context if available:

  search_graph(project=CBM_PROJECT, name_pattern=<suspect>)
  trace_path(project=CBM_PROJECT, direction="inbound")
  trace_path(project=CBM_PROJECT, direction="outbound")
  

Phase 4 — Instrument (one variable at a time)

Test hypothesis #1 first. Change ONE thing to observe ONE signal:

• Add targeted log/assertion near the suspect code
• Run feedback loop → confirm or refute
• Remove instrumentation after each test — never accumulate debug logs
• If refuted → move to hypothesis #2
• Stop when hypothesis is confirmed