revealui-debugging

---
name: revealui-debugging
description: |
  Systematic debugging workflow for RevealUI. Use when encountering any bug, test failure,
  unexpected behavior, error, or broken functionality. Prevents shotgun debugging.
---

# RevealUI Debugging Workflow

When something breaks, follow this process. Do not skip steps.

## The Process

### 1. Reproduce

- Get the exact error message, stack trace, or unexpected output
- Find the minimal reproduction case
- Confirm it reproduces consistently (not flaky)
- If it only fails under `turbo run test`, see `$revealui-testing` for concurrency triage

### 2. Hypothesize

- Form ONE specific hypothesis about the root cause
- Write it down before changing any code
- Base it on evidence (error message, stack trace, git blame), not intuition

### 3. Validate

- Design a test or check that confirms/refutes your hypothesis
- Run it
- If refuted, form a new hypothesis — do not stack unrelated fixes

### 4. Fix Narrowly

- Change the minimum code to fix the root cause
- Do not refactor surrounding code
- Do not fix adjacent issues you noticed along the way (file them separately)

### 5. Verify

- Run the original failing test/scenario
- Run `pnpm --filter <package> test` to check for regressions
- Run `npx biome check --write <file>` on changed files

### 6. Commit

- One commit for the fix
- Format: `fix(scope): description of what was broken`

## Anti-Patterns

- Changing multiple things at once ("shotgun debugging")
- Fixing symptoms instead of root causes
- Adding try/catch blocks to silence errors
- Increasing timeouts to hide race conditions
- Reverting to "known good" without understanding what broke
- Asking "does this fix it?" without a hypothesis

## Common RevealUI Debugging Paths

| Symptom | First Check |
|---------|------------|
| Import error | Package built? `pnpm --filter <pkg> build` |
| Type error across packages | `pnpm typecheck:all` — check `workspace:*` versions |
| Test passes alone, fails in gate | Concurrency pressure — see `$revealui-testing` |
| DB/vector query error in unexpected path | Check you use the single `@revealui/db` Drizzle client — see `$revealui-db` |
| Biome error after edit | Run `npx biome check --write <file>` |

More agent context in RevealUIStudio/revealui

10 other files this repository gives its agents.