debug— agent skill

Investigate the issue: $ARGUMENTS

Hard rule: do NOT write any fix until Phase 3 is reached and the user (or the evidence in Phase 2) has confirmed the root cause.

Phase 1 - Evidence

why-no-hook: skill workflow guidance; each step requires understanding the surrounding context (repo, task shape, prior state).

Gather, do not theorize. Save findings to .claude/state/research/YYYY-MM-DD-debug-<short-slug>.md.

• If given a Sentry issue (short ID like PROJECT-ABC, numeric ID, or sentry.io URL), fetch the digest first via the sentry-issue skill: ~/.agents/skills/sentry-issue/scripts/sentry-issue.sh <id>. Full payloads land in /tmp/sentry-{issue,event}-<id>.json for deeper jq queries. (review-time: see section note)
• Reproduce locally if feasible. Capture exact error, stack trace, request ID, timestamp. (review-time: see section note)
• Pull logs (Sentry, Cloud Run, container, browser console) for the affected window. (review-time: see section note)
• git log -p --since='2 weeks ago' -- <suspect-paths> to surface recent changes that touched the code path. (review-time: see section note)
• Confirm scope: how many users / requests / environments are affected. (review-time: see section note)
• Check related state: env vars set on the deployed service, DB row state, feature flags, recent deploys. (review-time: see section note)

If the user already supplied a hypothesis, treat it as a candidate but still gather evidence to confirm or reject.

Build a red-capable feedback loop

Before hypothesising, build a tight, red-capable feedback loop - one command (a failing test, a curl against a running server, a CLI invocation diffing output, a replayed trace) that you have already run at least once and that goes red on _this_ bug and green once fixed. Tighten it: faster, sharper signal, more deterministic (pin time, seed RNG). For a flaky bug, raise the reproduction rate until it's debuggable rather than chasing a clean repro. Then minimise - shrink to the smallest scenario that still goes red, cutting inputs, config, and steps one at a time. (review-time: loop construction is creative work, not pattern-checkable)

No red-capable command, no Phase 2 - jumping to a hypothesis before the loop exists is the exact failure this skill prevents. If you genuinely cannot build one (production-only, no local repro), say so explicitly, list what you tried, and ask the user for environment access or a captured artifact (HAR, log dump, core dump) before proceeding. (review-time: gate is a judgment about whether a real red-capable loop exists)

Phase 2 - Hypotheses

List 3-5 possible root causes ranked by evidence strength - generating several up front stops you anchoring on the first plausible idea. For each:

• Hypothesis - one line. (review-time: see section note)
• Prediction - the falsifiable test it implies: "if this is the cause, then changing X makes the bug disappear / changing Y makes it worse." If you can't state a prediction, it's a vibe - sharpen or discard it. (review-time: falsifiability judgment, not pattern-checkable)
• Evidence for - log lines, commits, or code paths that support it (with file:line refs). (review-time: see section note)
• Evidence against - what would have to be true that isn't. (review-time: see section note)
• Cheapest verification - what one command, query, or read would confirm or rule it out. (review-time: see section note)

Pick the top candidate. If two are tied or the user has a strong prior, ask the user to choose. Do not proceed to Phase 3 on a guess.

Phase 3 - Fix

• Smallest change that fixes the root cause first, per AGENTS.md. State the change before applying it. (review-time: see section note)
• Add a regression test that reproduces the original failure and now passes - only at a correct seam that exercises the real bug pattern; if no such seam exists, that itself is the finding, note it and hand off to /improve-codebase-architecture. (review-time: see section note)
• Remove all temporary instrumentation before committing - tag every debug log with a unique prefix like [DEBUG-a4f2] when you add it, so cleanup is a single grep. (review-time: see section note)
• Run /verify-done (lint + typecheck + test + build). (review-time: see section note)
• Commit on a feature branch with a conventional message that names the root cause. (review-time: see section note)
• Open a PR per mr skill. PR body: link to the alert/log, root cause statement with evidence, and why this fix is correct. (review-time: see section note)

Anti-patterns - reject these

• Adding retry / fallback / try-catch as a "fix" before root cause is confirmed. (review-time: see section note)
• Introducing new abstractions, services, or workspaces as part of a debug fix. (review-time: see section note)
• Editing logs to make the symptom disappear. (review-time: see section note)
• Leaving untagged debug instrumentation in the code after the fix. (review-time: see section note)
• Expanding scope ("while I'm here, let me also..."). (review-time: see section note)
• Pushing before all checks pass green locally. (review-time: see section note)