Debug

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

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

3. 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

4. If the user provided a Sentry issue URL or error ID, query Sentry for the full stack trace and event details.
5. 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.

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.

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.

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.

Load relevant skills before diving in:

• Load skills matching the technologies used in the project (discover from package.json).
• Common examples: backend framework skills, ORM/database skills, frontend framework skills, queue/worker skills.
• Read CLAUDE.md and package.json to identify the project's tech stack before selecting skills.

When the bug involves library API misuse, version-specific behavior, or unclear method signatures, query Context7 for up-to-date documentation:

1. mcp__context7__resolve-library-id — resolve the library name (e.g., "fastify", "drizzle-orm", "bullmq") to its Context7 ID.
2. mcp__context7__query-docs — query with the specific API, method, or error message you're investigating.

Use Context7 when:

• The error message references a library API you're unsure about.
• You suspect a breaking change between versions (check the project's package.json for installed versions first).
• The stack trace points to library internals and you need to understand expected behavior.
• You need to verify correct usage patterns for any project dependency.

See references/debug-dispatch.md for the agent prompt templates and dispatch patterns.

Each debugging agent should use Context7 (mcp__context7__resolve-library-id + mcp__context7__query-docs) to verify library API usage when the bug involves unclear method signatures, version-specific behavior, or suspected API misuse. Include this instruction in agent prompts — see references/debug-dispatch.md.

1. Re-run the reproduction — the original error should no longer occur.
2. Quality gates — run the project's type checking, linting, and testing commands for every affected package. Discover available commands from package.json scripts (e.g., tsc, lint, test).
3. Browser verification (for user-facing bugs) — use Playwright or Chrome DevTools to navigate to the affected page and confirm the fix works visually.
4. Regression check — verify the fix doesn't break related functionality. Run the full test suite for affected packages.

If any step fails, return to phase 5 and fix the issue. Re-run all verification steps from the beginning.

Frontend → API boundary

• CORS errors → check server CORS config
• 401/403 → check auth middleware, token expiry, cookie settings
• Wrong data shape → compare shared schema/type definitions with API response

API → Database boundary

• "relation does not exist" → migration not applied
• Empty results → wrong query conditions, check WHERE clause
• Connection errors → Docker not running, pool exhausted

API → Redis/Queue boundary

• Jobs not processing → worker not started, Redis down, wrong queue name
• Duplicate jobs → missing deduplication, idempotency key
• Stalled jobs → worker crashed without ack, check stall interval

Frontend rendering

• Hydration mismatch → server/client content differs, date formatting, conditional rendering
• Blank page → unhandled error in RSC, check error.tsx boundaries
• Infinite loading → API call hanging, missing Suspense boundary

Do not add explanations, caveats, or follow-up suggestions unless the user asks.