synaptiai Debugging Patterns
Contract
Iron law: find and prove the root cause before attempting any fix; a symptom fix is a failure. Invoked by /flow:debug Phases 1–3 (evidence → hypotheses → fix), by /flow:start and /flow:resolve on demand whenever a build, test, server-start, smoke, E2E, or visual step fails (no bug label required), and by the error-handler-inspector agent. Returns the confirmed root cause with evidence, the hypothesis table with each result, a reproducing test that failed before the fix and passes after, and a full-suite run with no regressions. Permitted skips: none — a clear error message shortens the investigation (one or two hypotheses) but never removes the reproducing test.
Evidence Before Theory
Read the full error message and stack trace first — never skim, never start with "let me understand the code." Then git log --oneline -10 and git diff HEAD~3..HEAD --stat for recent changes. Reproduce the failure; if you cannot reproduce it you cannot verify a fix. Trace backward from the error, checking inputs, API responses, and config values at each boundary, and only then read code.
Hypothesis Discipline
Form at most debugging.maxHypotheses (default 3) hypotheses at a time. More means insufficient evidence — return to evidence gathering. Create one task per hypothesis:
TaskCreate("Hypothesis 1: {theory}", "Confidence: High\nTest: {specific test}\nEvidence: {what points here}")
Rules:
- Test highest confidence first, ONE at a time — never change two things simultaneously.
TaskUpdate(status: "in_progress")before testing;TaskUpdate(status: "completed")after, recording confirmed or disproven. A disproven hypothesis is progress.- Write all hypotheses down before testing any, and actively seek disconfirming evidence for the leading one.
- Before blaming the last change, check whether the bug predates it (
git stash && test). Check simple causes (typo, wrong variable, off-by-one) before elaborate ones.
Display the table:
| # | Hypothesis | Confidence | Test | Result |
|---|
Fix Validation
Write a test that reproduces the bug BEFORE fixing. If it does not fail, you have not found the bug.
- Write the failing test; confirm it fails for the right reason.
- Implement the minimal fix.
- Confirm the test passes.
- Run the full suite — no regressions.
Track as TaskCreate("Fix validation", ...); TaskList must show every hypothesis and the fix task completed before returning.
Verification Failure Mode
When invoked because a verification step failed (build, test, server start, smoke, E2E, visual): read the output fully, form one or two hypotheses, fix, re-verify. Iteration ceilings belong to the caller (closedLoop.maxBuildIterations, closedLoop.maxServerRetries, closedLoop.maxDebugIterations). The user never has to supply logs or say what went wrong — you have the same output.
Stop Conditions
| Trigger | Action |
|---|---|
| 3+ failed fix attempts | Stop fixing forward; the problem is architectural. Return to EXPLORE. |
| Cannot explain current behavior | Do not guess. Add logging and assertions; investigate more. |
| Tunnel vision (>30 min on one theory) | Step back; list what you KNOW vs what you ASSUME. |
| Fix works but you cannot explain why | Revert. An unexplained fix is a time bomb. |
Not Fixes
A try-catch that hides the error, "quick fix now, proper fix later", or "probably a race condition" without timing evidence are symptom fixes. "I know what's wrong" still requires proof — if you are right it takes thirty seconds. "It works on my machine" means the bug is in the environment difference; investigate that.