debug

<live_context> Recent git changes (regression candidates): !git log --oneline -10 2>/dev/null || echo "(not a git repo)"

Working tree status: !git status --short 2>/dev/null || echo "(not a git repo)" </live_context>

<trigger_examples>

• "Debug why the form submission fails with a 500 error"
• "The dashboard page shows a blank screen after login"
• "API returns 403 but the user should be authorized"
• "Investigate this Sentry issue: PROJECT-123"
• "The form submits but nothing appears in the list"
• "Debug the notification queue — jobs are stuck" </trigger_examples>

<phase_1_triage> Classify the bug before investigating. This determines which agents to dispatch.

1. Read the error description, stack trace, or reproduction steps provided by the user.
2. Determine the affected layers:

Layer	Signals
Frontend	UI doesn't render, hydration errors, blank pages, console errors, wrong data displayed
API	HTTP error codes (4xx/5xx), validation failures, timeout, wrong response body
Database	Missing data, wrong query results, migration issues, connection errors
Queue/Worker	Jobs stuck, not processing, duplicate execution, Redis connectivity
Infrastructure	Docker containers down, ports in use, env vars missing
Cross-cutting	Data flows correctly in one layer but breaks in another

1. Check for quick context — run these in parallel:

# Recent changes that might have introduced the bug
git log --oneline -10
git diff HEAD~3 --stat

# Infrastructure health
docker compose ps

1. If the user provided a Sentry issue URL or error ID, query Sentry for the full stack trace and event details.
2. If the user mentions production errors, check PostHog error tracking for frequency and user impact.

State the triage result to the user:

TRIAGE: [layer(s)] — Brief description of what appears to be happening. </phase_1_triage>

<phase_2_execution_mode> Based on the triage, decide the execution mode:

SINGLE-LAYER — The bug is isolated to one layer. Debug directly without dispatching agents.

MULTI-LAYER — The bug spans 2+ layers. Act as orchestrator and dispatch specialized debugging agents.

State the decision:

EXECUTION MODE: SINGLE-LAYER — I will investigate and fix this directly.

OR

EXECUTION MODE: MULTI-LAYER — I will dispatch specialized agents to investigate each layer in parallel. </phase_2_execution_mode>

<phase_3_reproduce> Reproduce the bug before investigating. Never fix what you can't reproduce.

<reproduction_strategies>

API bugs — Use curl or Bash to hit the endpoint directly:

# Discover the API base URL and endpoints from CLAUDE.md, package.json, or route files
curl -v http://localhost:<port>/<endpoint> | jq .

Frontend bugs — Use browser automation MCPs:

1. Call mcp__chrome-devtools__list_pages or mcp__plugin_playwright_playwright__browser_tabs to check current state.
2. Navigate to the affected page and take a screenshot.
3. Check the browser console for errors.
4. Inspect network requests for failed API calls.

Queue/Worker bugs — Check Redis and BullMQ state:

# Check Redis connectivity
redis-cli ping

# Check queue state — discover the dev command from package.json scripts
# e.g., yarn dev, npm run dev, or the relevant workspace command

Database bugs — Query directly:

# Discover database credentials and container names from docker-compose.yml or .env
docker compose exec <db-container> psql -U <user> -c "SELECT * FROM ... LIMIT 5"

If reproduction fails, add strategic logging and retry. See references/debug-dispatch.md for logging patterns. </reproduction_strategies> </phase_3_reproduce>

<phase_4_investigate> With the bug reproduced, investigate the root cause.

<single_layer_investigation> Follow the data flow from the error point backward:

1. Read the source code at the error location.
2. Trace inputs — where does the data come from? What transformations happen?
3. Form a hypothesis about the root cause.
4. Test the hypothesis — add logging, inspect state, check the database.
5. If the hypothesis is wrong, form a new one based on what you learned.