---
name: debug
description: Structured debugging workflow — reproduce first, gather evidence, trace root cause, fix with minimal scope. Use when the user asks to debug, investigate, trace, or fix a bug.
---

# Debugging Workflow

Reproduce the issue, gather evidence, trace the root cause, then apply the smallest fix. No guessing, no unrelated changes.

## When to Apply

- User asks to "debug", "investigate", "trace", or "fix" a bug
- Something is broken and the cause isn't immediately obvious
- User reports unexpected behavior

## Workflow

### 1. Reproduce the issue

- Get exact error messages and repro steps
- Reproduce the issue yourself before changing any code

### 2. Gather an evidence pack

Before changing code, capture:

- Error messages and stack traces
- Relevant logs (server, client, build output)
- Minimal repro steps
- System boundary involved (API, database, external service, browser, CLI, etc.)
- Network requests/responses if applicable

**Use the repo's purpose-built diagnostics first:**

| Symptom | Tool / doc |
|---------|-----------|
| `npm run verify` failure | `npm run --workspace @skytest/web verify:explain` — attributes the failure to its checker |
| Runs stuck queued / claiming / dispatch issues | `docs/maintainers/runner-queue-diagnostics.md` |
| Frontend ↔ runtime integration (SSE, run status, artifacts) | `docs/maintainers/frontend-runtime-debugging.md` |
| Android device/emulator runtime | `docs/maintainers/android-runtime-maintenance.md` |
| Unsure where a behavior lives | Task Routing table in `CLAUDE.md` |

### 3. Trace the root cause

- Trace data flow from the symptom to the root cause
- Don't guess — follow the evidence through the code
- Trace across service boundaries, not just within a single file:
  - request -> middleware -> handler -> service -> data layer -> response
- If the bug is in deprecated or superseded code, confirm whether the correct fix is removal rather than patching

### 4. Write a failing test

- Write a failing test or minimal repro that demonstrates the bug
- Skip only if the project has no test harness; note the skip

### 5. Apply the smallest fix

- Implement the minimal fix that addresses the root cause
- Re-verify the fix passes the failing test and doesn't break existing tests

### 6. Report

- Summarize: root cause, fix applied, tests run
- Note any follow-ups or related issues discovered

## Guidelines

- **Scope freeze**: Do not fix unrelated issues, refactor surrounding code, or add polish. Only fix the reported bug.
- **Evidence over guesses**: Always trace, never assume
- **Safety snapshot**: Before any scope cleanup, create a backup via `git stash push -u -m "wip backup"` or a WIP commit
- **No destructive git operations** (`git restore`, `git checkout -- <file>`, `git reset --hard`, `git clean`, `git rebase`, force-push) without explicit user permission
