| name | debug-runbook |
| description | Structured debugging for production and staging issues. Maps symptoms to tools, queries, and data sources (Sentry, PostHog, wrangler logs, console, simulator logs). Use when something is "not working", "broken", "failing in prod", "500 error", "check logs", "check sentry", "why is this happening", or when debugging a deployed service or mobile app.
|
Debug Runbook
Symptom-first workflow
Every debugging session follows the same loop:
- Symptom — What does the user see? Exact error, behavior, or absence of expected behavior.
- Boundary — Where does the problem live? Client, edge worker, database, third-party service, CI pipeline.
- Tool — Pick the right data source for that boundary (see table below).
- Query — Pull logs, errors, events, or state from that source.
- Interpret — Read the data. Identify root cause vs. symptom.
- Fix — Address the root cause only. No workarounds, no band-aids.
Do NOT skip step 1. The user's description of the symptom determines which tool to reach for. Do NOT start by reading source code — start by reading production data.
Data source reference
| Tool | When to use | Access |
|---|
| Sentry MCP | Crash reports, unhandled exceptions, error grouping, stack traces, breadcrumbs | mcp__sentry__* tools |
| PostHog MCP | User behavior, feature flag state, session replay, funnel analysis | mcp__posthog__* tools |
wrangler tail | Live request/response logs from Cloudflare Workers | wrangler tail <worker-name> --format json |
wrangler deployments list | Verify which version is actually deployed | wrangler deployments list |
| iOS simulator logs | Console output from iOS simulator apps | xcrun simctl spawn booted log stream --level debug --predicate 'subsystem == "<bundle-id>"' |
| Chrome DevTools / console MCP | Browser console errors, network failures, DOM state | mcp__claude-in-chrome__read_console_messages, mcp__claude-in-chrome__read_network_requests |
gh run view | CI/CD pipeline failures, test output, deploy step logs | gh run view <run-id> --log-failed |
| Network tab | CORS errors, failed fetches, WebSocket disconnects | mcp__claude-in-chrome__read_network_requests |
Common symptoms (quick reference)
| Symptom | First step | Details |
|---|
| 500 error on deployed worker | wrangler tail the worker | symptom-map.md |
| App crashes on launch | Check Sentry for crash report | symptom-map.md |
| Feature works locally, broken in prod | Compare env vars and deployed version | symptom-map.md |
| Audio/media not playing | Check console for CORS or asset errors | symptom-map.md |
| Can't connect / stuck on loading | Network tab, WebSocket status, backend logs | symptom-map.md |
| Tests pass but feature broken | Verify tests actually ran against right target | symptom-map.md |
| CI failing | gh run view the failing run | symptom-map.md |
| Detox tests not running | Verify simulator booted and build exists | symptom-map.md |
Load references/symptom-map.md for detailed investigation steps, specific commands, and interpretation guidance.
Configuration
On first use, check for project-specific config at:
${CLAUDE_PLUGIN_DATA}/debug-runbook/config.json
Expected schema:
{
"sentry": {
"project_slug": "my-project",
"org_slug": "my-org"
},
"posthog": {
"project_id": "12345"
},
"workers": [
{
"name": "api-worker",
"url": "https://api.example.com",
"environment": "production"
}
],
"deployed_urls": {
"production": "https://app.example.com",
"staging": "https://staging.app.example.com"
},
"ios": {
"bundle_id": "com.example.app"
}
}
If config does not exist, ask the user:
- What services are involved? (Workers, iOS app, web app)
- Do they have Sentry/PostHog configured? What are the project identifiers?
- What are the worker names and deployed URLs?
Create the config file from their answers so subsequent runs skip setup.
Gotchas
These are real, recurring pain points. Read before debugging.
- Do not strip console.log in production builds. The user relies on logs for debugging. If a build tool removes them, that is a problem to fix, not a feature.
- Always verify deployed version matches expected commit before debugging code. Run
wrangler deployments list or check the deploy pipeline. If the wrong version is live, no amount of code reading helps.
- Check BOTH .dev.vars AND GitHub Actions secrets. They are independent stores. A secret present in one may be missing from the other.
- Wrangler secrets do not copy between environments. Setting a secret for production does not set it for staging. Check both:
wrangler secret list and wrangler secret list --env staging.
- Simulator vs. device behavior diverges. If the app works in simulator but not on a physical device, check: network/API URL configuration, HTTPS certificate pinning, camera/media permissions, and push notification setup.
- Simulator logs and device logs are accessed differently. Simulator:
xcrun simctl spawn booted log stream. Device: Xcode Console or idevicesyslog.
- Sentry and PostHog MCPs must be configured per-project. Check the MCP configuration (
/mcp) to verify the tools are available before trying to call them. If they are not listed, they are not connected.
- Feature flags in PostHog are evaluated per-environment. A flag enabled in dev may be disabled in production. Always check flag state for the environment you are debugging.
References
