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>