Debug Runbook

Debug Runbook

Symptom-first workflow

Every debugging session follows the same loop:

1. Symptom — What does the user see? Exact error, behavior, or absence of expected behavior.
2. Boundary — Where does the problem live? Client, edge worker, database, third-party service, CI pipeline.
3. Tool — Pick the right data source for that boundary (see table below).
4. Query — Pull logs, errors, events, or state from that source.
5. Interpret — Read the data. Identify root cause vs. symptom.
6. 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

Common symptoms (quick reference)

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:

1. What services are involved? (Workers, iOS app, web app)
2. Do they have Sentry/PostHog configured? What are the project identifiers?
3. 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