Debugmode

Debug Mode

Hypothesis-driven debugging with runtime instrumentation, background agent monitoring, git-safe cleanup, and automated regression tests.

Overview

Instead of guessing at fixes from static code analysis, Debug Mode collects runtime evidence first. It instruments code with strategic debug logs, uses background agents to monitor actual execution, proposes targeted fixes based on evidence, writes regression tests, and cleans up all instrumentation after the bug is confirmed fixed.

Core principle: Never propose a fix without runtime evidence. Hypothesize -> Instrument -> Observe -> Fix -> Verify -> Live Test -> Clean.

Five Iron Laws

1. No fixes without reproduction first — if you can't reproduce it, you can't prove you fixed it
2. No guessing — instrument and observe, never propose fixes from static reading alone
3. Never hang the terminal — detach background processes, use timeouts
4. Protect context window — logs go to file, then query surgically
5. Git-safe cleanup — use git restore . after committing reproduction test, never manually delete logs

Workflow

digraph debugmode {
  rankdir=TB;
  "User reports bug" -> "Safety: git branch + stash";
  "Safety: git branch + stash" -> "Discover: scan project + recent changes";
  "Discover: scan project + recent changes" -> "Generate 3-5 hypotheses";
  "Generate 3-5 hypotheses" -> "Write reproduction script/test";
  "Write reproduction script/test" -> "Commit reproduction test";
  "Commit reproduction test" -> "Instrument code (dirty working tree)";
  "Instrument code (dirty working tree)" -> "Auto-reproduce or tell user steps";
  "Auto-reproduce or tell user steps" -> "Collect logs to .claude/debug.log";
  "Collect logs to .claude/debug.log" -> "Background agent analyzes evidence";
  "Background agent analyzes evidence" -> "Root cause found?";
  "Root cause found?" -> "git restore . (clean instrumentation)" [label="yes"];
  "Root cause found?" -> "Refine hypotheses + re-instrument" [label="no"];
  "Refine hypotheses + re-instrument" -> "Auto-reproduce or tell user steps";
  "git restore . (clean instrumentation)" -> "Apply targeted fix";
  "Apply targeted fix" -> "Red-to-green verification";
  "Red-to-green verification" -> "Bug fixed?";
  "Bug fixed?" -> "Live Monitor + User Test" [label="yes"];
  "Bug fixed?" -> "Background agent analyzes evidence" [label="no"];
  "Live Monitor + User Test" -> "Agent monitors logs at server";
  "Agent monitors logs at server" -> "User tests at localhost";
  "User tests at localhost" -> "New errors caught?";
  "New errors caught?" -> "Agent reports + re-diagnose" [label="yes"];
  "Agent reports + re-diagnose" -> "Apply targeted fix";
  "New errors caught?" -> "User confirms fix works" [label="no"];
  "User confirms fix works" -> "Kill server + cleanup";
  "Kill server + cleanup" -> "Save bug knowledge to memory";
  "Save bug knowledge to memory" -> "Done";
}

Steps

Phase 0: Safety First

Before touching anything:

1. Create a debug branch (if not already on a feature branch):

``bash git checkout -b debug/ ``

1. Stash any uncommitted work:

``bash git stash push -m "pre-debug stash" ``

1. Scan the project for infrastructure context:

• What test framework exists? (vitest, jest, playwright, pytest, etc.)
• What's the dev server command? (pnpm run dev, npm start, etc.)
• Recent git changes to affected files: git log --oneline -15 --
• Check for existing related tests

Phase 1: Understand the Bug

• Read the user's bug description carefully
• Identify the affected files, routes, components, or services
• Read all relevant source code before forming any opinion
• Trace the call chain — follow data flow from entry point to where the bug manifests
• Check for recent changes: git log --oneline -10 --

Phase 2: Generate Hypotheses

Form 3-5 ranked hypotheses about what could cause the bug. Include non-obvious possibilities.

Format each hypothesis with evidence criteria:

HYPOTHESIS 1 (HIGH): [Short title]
Why: [Reasoning based on code reading]
Evidence to CONFIRM: [What runtime data would prove this]
Evidence to DENY: [What runtime data would disprove this]
Test: [What debug log would confirm/deny this]
Location: [File:line where to instrument]

HYPOTHESIS 2 (MEDIUM): [Short title]
...

Ranking rules:

• HIGH — Code path analysis strongly suggests this
• MEDIUM — Plausible but needs runtime evidence
• LOW — Non-obvious but worth ruling out

Present hypotheses to the user before instrumenting.

Phase 3: Write Reproduction Script

Before adding any debug logs, write a reproduction test or script that triggers the bug.

Reproduction strategy (pick best fit):

| Bug Type | Best Strategy | Example | |----------|---------------|---------| | Logic error | Failing unit test | vitest test case that asserts wrong output | | API response | curl / HTTP request | curl -X POST localhost:3000/api/... | | Race condition | Loop 50x in script | Script that hammers endpoint repeatedly | | UI/state bug | Playwright e2e test | Navigate + click + assert | | State corruption | Standalone repro script | Script that reproduces the state | | Flaky test | Loop 50x | Run test in loop to catch intermittent fail | | CORS/headers | curl -v | Verbose HTTP inspection |

Commit the reproduction test immediately:

git add 
git commit -m "test: add reproduction for "

This is critical — the reproduction test is committed BEFORE instrumentation, enabling git-safe cleanup later.

Phase 4: Instrument Code with Debug Logs

Now add structured, tagged debug logs to the working tree (dirty state).

Log format standard — use stderr to avoid contaminating app output:

// TypeScript / Next.js — use console.error for stderr
// #region DEBUG
console.error('[DEBUG-MODE][H1:auth-check][validateUser]', JSON.stringify({
  userId, isAuthenticated, sessionExpiry: session?.expires,
  timestamp: new Date().toISOString()
}));
// #endregion DEBUG

# Python
# #region DEBUG
import json, sys, datetime
print(f"[DEBUG-MODE][H1:auth-check][validate_user] {json.dumps({'user_id': user_id, 'is_authenticated': is_authenticated, 'timestamp': datetime.datetime.now().isoformat()})}", file=sys.stderr)
# #endregion DEBUG

// Go
// #region DEBUG
fmt.Fprintf(os.Stderr, "[DEBUG-MODE][H1:auth-check][ValidateUser] userId=%s isAuth=%v timestamp=%s\n",
    userId, isAuthenticated, time.Now().Format(time.RFC3339))
// #endregion DEBUG

Log tag anatomy:

[DEBUG-MODE][H:][] key=value ...

• [DEBUG-MODE] — universal prefix for bulletproof grep cleanup
• [H:] — maps to hypothesis, enables filtering: grep '\[H1'
• [] — where in the code
• key=value — structured data capture

Instrumentation rules:

• Wrap ALL debug code in // #region DEBUG / // #endregion DEBUG markers
• Tag every log with its hypothesis ID (H1, H2, H3)
• Use console.error / stderr — never console.log / stdout (avoids polluting app output)
• Log at entry/exit points of suspected functions
• Capture variable states, not just "reached here"
• Add logs at branching points (if/else, switch, error handlers)
• Keep logs focused — 3-5 strategic points per hypothesis, not 20+ scattered
• Never instrument production-only code paths without user awareness

Phase 5: Reproduce and Collect Evidence

Option A: Auto-reproduce (preferred)

If tests or reproduction scripts exist, use a background agent to run them and collect logs:

# Redirect all output to .claude/debug.log
mkdir -p .claude
node repro-script.js > .claude/debug.log 2>&1

# Or for test-based reproduction
pnpm run test:run 2>&1 | tee .claude/debug.log

# Or for dev server bugs — detach the server first
nohup pnpm run dev > .claude/debug-server.log 2>&1 &
SERVER_PID=$!
sleep 5
# Run reproduction steps...
curl -s http://localhost:3000/api/affected-route >> .claude/debug.log 2>&1
kill $SERVER_PID

CRITICAL: Always detach long-running processes — never let pnpm run dev block the terminal:

nohup  > .claude/debug-server.log 2>&1 &
SERVER_PID=$!
sleep 3  # Wait for startup
# ... do work ...
kill $SERVER_PID  # Always clean up

Option B: User-assisted reproduction

When auto-reproduce isn't possible (UI bugs, browser-specific issues), give the user explicit, numbered steps:

To test this, please:
1. Restart the dev server (Ctrl+C then `pnpm run dev`)
2. Hard refresh the browser (Cmd+Shift+R / Ctrl+Shift+R)
3. Clear browser cache if needed (DevTools → Application → Clear Storage)
4. Navigate to [specific page/route]
5. Do [specific action that triggers the bug]
6. Check the TERMINAL (not browser console) for lines starting with [DEBUG-MODE]
7. Copy-paste the terminal output back to me, OR I'll read it from .claude/debug.log

Expected: You should see debug output with hypothesis tags like [H1], [H2].
If the bug reproduces, I'll have the runtime evidence I need.

Always specify:

• Whether to restart the server (usually yes)
• Whether to hard refresh the browser
• Whether to clear cache/cookies/localStorage
• The exact user actions to perform
• Where to look for output (terminal vs browser console)
• Whether user needs to copy/paste output or agent reads from file

Phase 6: Background Agent Analysis

Launch a background agent to analyze collected evidence:

Background agent prompt template:

You are analyzing debug output for a debugging session.

Bug description: [bug description]

Hypotheses being tested:
- H1 (HIGH): [description] — Evidence to confirm: [criteria]
- H2 (MEDIUM): [description] — Evidence to confirm: [criteria]
- H3 (LOW): [description] — Evidence to confirm: [criteria]

Instructions:
1. Read .claude/debug.log (or .claude/debug-server.log)
2. Extract all lines containing [DEBUG-MODE]
3. For each hypothesis, classify as:
   - CONFIRMED: Evidence directly supports this as root cause
   - DENIED: Evidence contradicts this hypothesis
   - INCONCLUSIVE: Not enough data, need more instrumentation
4. For CONFIRMED hypotheses, extract the specific data that proves it
5. For DENIED hypotheses, explain what the data showed instead
6. Flag any UNEXPECTED errors, stack traces, or anomalies not covered by hypotheses
7. Suggest what additional instrumentation would help for INCONCLUSIVE hypotheses

Query log surgically to protect context window:
- grep '[DEBUG-MODE]' .claude/debug.log
- grep '[H1' .claude/debug.log
- grep -C 2 'Exception\|Error\|FATAL' .claude/debug.log | head -n 50

Do NOT attempt fixes. Only collect, analyze, and report evidence.

If evidence is INCONCLUSIVE for all hypotheses:

1. Generate new hypotheses based on what the data DID reveal
2. Add more targeted instrumentation
3. Repeat from Phase 5

Phase 7: Git-Safe Cleanup + Fix

This is the key innovation — commit-then-instrument pattern:

1. Clean all instrumentation with git restore (since reproduction test was already committed):

``bash git restore . `` This perfectly removes ALL debug logs without risk of syntax corruption. No manual deletion needed.

1. Verify clean state:

``bash grep -r "\[DEBUG-MODE\]" . --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" --include="*.go" --include="*.rb" --include="*.php" # Should return nothing ``

1. Apply the targeted fix — should be minimal (often 2-5 lines):

• Fix the root cause, not the symptom
• If fix touches more than 10-15 lines, pause and verify you're addressing root cause

1. Commit the fix separately:

``bash git add git commit -m "fix(): " ``

Phase 8: Red-to-Green Verification

Prove the fix actually works with the committed reproduction test:

1. GREEN check — Run reproduction test, should PASS now:

``bash # Use whatever test runner the project uses: # npm test -- # pytest # go test -run ./... ``

1. RED check (optional but gold standard) — Temporarily revert fix, reproduction should FAIL:

``bash git stash push -m "verify-red" # Run repro test again — should FAIL without the fix git stash pop # Restore fix ``

1. Full verification suite — run whatever checks the project uses:

``bash # Detect and run the project's standard checks. Examples: # TypeScript: npx tsc --noEmit # Build: npm run build / pnpm run build / yarn build # Lint: npm run lint / pnpm run lint # Tests: npm test / pnpm run test / pytest / go test ./... # Run ALL checks that CI would run — check the CI config if unsure ``

If all automated checks pass, proceed to live verification.

Phase 9: Live Monitoring + User Testing

This is where the fix gets battle-tested in the real application. A background agent launches the dev server, monitors logs for runtime errors, and the user tests the actual app — while the agent watches for anything going wrong behind the scenes.

This phase matters because automated tests can't catch everything — UI regressions, unexpected side effects in other features, and production-like behavior all need human eyes. But instead of the user testing blind, an agent is watching the server logs in real-time, ready to catch and report errors the user might not even notice.

Step 1: Launch the dev server with a monitoring agent

Spawn a background agent that starts the dev server and continuously monitors its output:

Background monitoring agent prompt:

You are a live server monitor for a debugging session.

Bug that was fixed: [bug description]
Fix that was applied: [brief description of the fix]

Your job:
1. Start the dev server and monitor its output for errors.
2. Continuously watch the log file for new errors, exceptions, or warnings.
3. When you detect an issue, report it immediately with:
   - The exact error message and stack trace
   - Which file/line triggered it
   - Whether it looks related to the fix or is a separate issue
   - Timestamp of when it occurred

Instructions:
1. Start the server (detached, logging to file):
   mkdir -p .claude
   nohup  > .claude/live-server.log 2>&1 &
   echo $! > .claude/server.pid

2. Wait for the server to be ready:
   - Tail the log until you see the "ready" or "listening" message
   - Verify with: curl -s -o /dev/null -w "%{http_code}" http://localhost:
   - If server fails to start, report the error immediately

3. Once server is running, enter monitoring loop:
   - Every 5 seconds, check .claude/live-server.log for new content
   - Look for: Exception, Error, FATAL, panic, Traceback, WARN, unhandledRejection
   - Track the last-read position so you only report NEW errors
   - Also watch for server crashes (check if PID is still alive)

4. Keep monitoring until told to stop. Do NOT kill the server yourself.

IMPORTANT:
- Use `tail -f` piped to grep for efficient monitoring
- Report errors as they happen — don't batch them
- Distinguish between the FIXED bug recurring vs NEW issues
- If the server crashes, report immediately and attempt restart

Step 2: Tell the user to test

Once the background agent confirms the server is running, tell the user:

Fix applied and all automated tests pass. I've started the dev server
with a background agent monitoring for errors in real-time.

The app is running at: http://localhost:

Please test the fix:
1. Open http://localhost: in your browser
2. Hard refresh (Cmd+Shift+R / Ctrl+Shift+R)
3. [Specific steps to test the original bug]
4. [Steps to test related features that might be affected]
5. Try anything else that feels relevant

I'm watching the server logs in the background. If any errors
occur — even ones you don't notice in the browser — I'll catch
them and report immediately.

When you're done testing, let me know:
- "Looks good" → I'll wrap up
- "Found an issue: [description]" → I'll chec

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ChiFungHillmanChan](https://github.com/ChiFungHillmanChan)
- **Source:** [ChiFungHillmanChan/shipwright](https://github.com/ChiFungHillmanChan/shipwright)
- **License:** MIT

Install and usage instructions live in the source repository linked above.