Runbook: Incident Response

Purpose: Diagnose and resolve issues with BoB tooling, warp-drive, or project dev environments When to use: Something is broken — warp-drive stuck, dev environment down, provisioning failed, or unexpected behavior Prerequisites: Access to the affected project directory Estimated time: 5-15 minutes

Steps

1. Identify the problem domain

Determine which system is affected:

Symptom	Domain	Go to
Warp-drive stuck or erroring	State machine	Step 2
Dev environment won’t start	Dev lifecycle	Step 3
Provisioning/symlinks broken	Provisioning	Step 4
Hooks blocking operations	Hook system	Step 5
Unexpected Claude behavior	Configuration	Step 6

2. Diagnose warp-drive issues

Check current state:

node ~/.claude/scripts/warp-drive/state-machine.js status "$(pwd)"

Expected output: JSON with phase, stale status, and budget info.

Decision tree:

• If stale: true → Previous session died. Reset: node ~/.claude/scripts/warp-drive/state-machine.js reset "$(pwd)"
• If budgetExceeded present → Phase timeout or retry limit hit. Either extend budgets in settings.local.json under _workflow, or abort: node ~/.claude/scripts/warp-drive/state-machine.js abort "$(pwd)"
• If phase is aborted → Complete cleanup per the abort instructions in the state machine output
• If gate blocking → Check _workflow.verification_gates in settings.local.json

After fix, restart: /warp-drive

3. Diagnose dev environment issues

Run health check:

~/.claude/scripts/dev-lifecycle/health-check.sh "$(pwd)"

Expected output: Health status with endpoint check result.

Decision tree:

• If server not running → Start it: ~/.claude/scripts/dev-lifecycle/dev-up.sh "$(pwd)" --verbose
• If server running but unhealthy → Check logs for the server process
• If migrations failed → Check the migration command in dev.json and run manually
• If seed data failed → Check seed/ scripts for errors, run manually

Full recovery:

~/.claude/scripts/dev-lifecycle/dev-up.sh "$(pwd)" --verbose

4. Diagnose provisioning issues

Check current state:

cdprov --status

Expected output: List of provisioned items with symlink status (OK/BROKEN/MISSING).

Decision tree:

• If symlinks broken → Re-provision: cdprov
• If manifest missing → Create one: cdprov --init
• If wrong items → Edit ~/.claude/provisions/<project>.json and re-provision

5. Diagnose hook issues

Hooks are configured in .claude/settings.json and .claude/settings.local.json.

Check which hooks are active:

cat .claude/settings.json | jq '.hooks' 2>/dev/null
cat .claude/settings.local.json | jq '.hooks' 2>/dev/null

Common hook issues:

• Hook script not executable → chmod +x <script>
• Hook reading wrong JSON field → Hooks receive data via stdin as JSON, not magic variables
• Hook blocking legitimate operation → Check the gate conditions in the hook script

6. Diagnose configuration issues

Check for conflicting settings:

cat .claude/settings.json | jq '.' 2>/dev/null
cat .claude/settings.local.json | jq '._automation, ._rdb, ._workflow' 2>/dev/null

Common issues:

• Automation level not set → /automation level 2
• Permissions too restrictive → Check allowedTools in the active profile
• RDB enabled but bridge down → /rdb off to switch back to terminal

Troubleshooting

Symptom	Likely Cause	Fix
“No active state” on warp-drive commands	State file deleted or never created	Start fresh: /warp-drive
“Invalid transition” error	Trying to skip a phase	Check current phase with status, follow the phase sequence
Permission denied on scripts	Not executable	chmod +x ~/.claude/scripts/**/*.sh
jq: command not found	jq not installed	brew install jq (macOS)
Git commit blocked by hook	Warp-drive not in committing phase	Complete current phase first, or reset warp-drive if stuck

Escalation

If this runbook doesn’t resolve the issue:

1. Collect diagnostics: cdb, git status, state file contents, recent git log
2. File a GitHub issue with the diagnostics attached
3. As a last resort, reset all state: node ~/.claude/scripts/warp-drive/state-machine.js reset "$(pwd)" and start fresh