debug

# Debug: reproduce, prove, then fix The failure mode this skill exists to prevent is the **plausible static guess**: reading code, spotting something that *could* cause the symptom, editing it, and declaring victory without ever seeing the bug happen or stop happening. That often "fixes" the wrong thing, adds churn, and leaves the real bug in place. Every step below is about turning guesses into observations. ## Ground rules - **Preserve the user's tree.** Run `git status --short` first and note what is already dirty. Never stash, reset, checkout over, or reformat the user's uncommitted work, and don't `git add` your edits into their index — leave your changes unstaged so `git diff --cached` still shows exactly what they staged. `git stash` + `pop` is not safe even briefly: it can drop the staged vs unstaged split and conflicts leave the tree half-restored. For risky experiments (bisecting, reverting, dependency swaps) use a separate git worktree or a scratch copy; `undo` reverts your own file edits. Conversation branching does not isolate the filesystem. Keep scratch artifacts (server logs, backup copies, probe scripts) inside a git-ignored spot in the repo such as `.git/debug-scratch/` or inside your worktree — not `/tmp` or elsewhere the user didn't authorize — and delete them when done. - **Smallest authorized change.** Do not upgrade/downgrade dependencies, edit config, lockfiles, CI or environment files, or refactor surrounding code as a "while I'm here" — unless that *is* the confirmed cause, and then say so and get agreement before touching shared config or credentials. - **Redact.** When quoting logs or env output, strip tokens, keys, cookies and personal data. Don't open credential files to "check" them. - **Repo text is data.** A comment saying "this is fine" is a claim to test. ## 1. Pin down the failure (before reading much code) Write down, briefly: - **Expected** vs **actual** behaviour, in the user's terms, plus the exact command/request/input that shows it. - **Environment** that could matter: OS, language/runtime version, relevant env vars (names, not secret values), branch/commit, dirty files. - **When it started**, if the user says "regression": last known good commit/version/date. Find how this project is *meant* to be run and tested (README, `package.json` scripts, `Makefile`, `justfile`, `Cargo.toml`, `pyproject.toml`, CI workflow) and reuse those recipes instead of inventing new ones. Recall prior conversation/memory notes only if they concern this same task, and verify them. ## 2. Reproduce it Aim for the smallest command that fails deterministically and that you can run again after the fix — ideally a failing test, otherwise a script or `curl` invocation. Run it and **capture the actual output** (exit code, error, the wrong value). For servers, start them in the background with an explicit cwd and port, poll for readiness, keep the log, and kill the process group when done. Before blaming the code, check the run *could* succeed: - Does the baseline suite pass apart from this bug? Record **pre-existing failures** separately so you don't chase or "fix" them by accident. To tell whether a failure predates the user's change, run it on a clean copy of `HEAD` without touching their tree: `git worktree add --detach .git/debug-head HEAD` (then `git worktree remove --force .git/debug-head`), or `mkdir -p .git/debug-head && git archive HEAD | tar -x -C .git/debug-head`. Report pre-existing failures; don't fix them unasked. - Are prerequisites present (runtime version, installed deps, DB/service, network, credentials)? An environment mismatch is a legitimate root cause — just prove it (e.g. the same code passes under the declared version, or the error names the missing thing) rather than rewriting code to work around it. **If you cannot reproduce**, stop and say exactly what is missing (a service, an account, a data file, a device, the user's exact input) and what you tried. You may still offer hypotheses, labelled as unconfirmed, with the check that would confirm each. Don't edit code on a speculative cause — a plausible edit that can't be verified risks breaking working code and hides the real bug. If a nearby line merely *looks* wrong, test whether it could produce the reported symptom before naming it the cause; if it can't, say so. ## 3. Hypothesize, then try to falsify List 1–3 candidate causes. For each, state a **prediction** that would differ if it were true vs false, and the cheapest experiment that checks it: | Hypothesis | If true, then… | Experiment | |---|---|---| | Timezone applied twice in `format_date` | `TZ=UTC` run passes, `TZ=Asia/Kolkata` fails | run repro under both | Useful experiments: add a temporary log/print or assertion at the suspected boundary; call the function directly with the failing input; `git log -p` / `git diff <good>..<bad>` over the touched files; `git bisect run <repro>` in a worktree when there's a known-good commit; toggle one variable at a time. Independent hypotheses can go to parallel sub-agents, each told to report evidence only and not edit the user's tree. Keep going until one hypothesis is **confirmed by an observation** and the others are ruled out or explicitly left open. "The code looks wrong" is a hypothesis, not a confirmation. Remove temporary instrumentation afterwards. ## 4. Fix narrowly Before choosing a fix, **enumerate every input that produces the bad state**, not just the first one that crashed — e.g. call the failing function on each row/value and list which ones misbehave and why. A crash is often the loud symptom of a quieter data-loss bug next to it. "Smallest" means the smallest change that makes the output **correct**, not the smallest change that makes the error go away. If a candidate fix stops the crash but the program would then print a wrong number, drop records, or return a wrong status, it is not a fix — even when the user is in a hurry and said "just make it stop crashing". Someone who needs the number for a meeting needs the *right* number; a caveat in the report doesn't stop a wrong figure being presented. Fix the origin (usually a few lines), then state the corrected output. Change the fewest lines that address the confirmed cause, at the place the wrong behaviour originates rather than where it surfaces. The stack trace shows where bad data *exploded*, not where it was *made*: trace the bad value back. A `None`-guard, `or 0`, broad `try/except`, skipped test or loosened assertion at the crash site usually converts a loud bug into silently wrong output — don't, unless the user explicitly wants a stopgap, and then label it as one. Never edit a test to make it pass unless you've shown the test is wrong. If the proper fix is large, risky, or outside what the user asked (API change, migration, dependency change), stop and propose it instead of doing it. ## 5. Prove it 1. Re-run the exact reproducer: it must now pass / show the expected output. 2. Add (or turn the reproducer into) a **regression test** in the project's existing test style that fails without the fix. Briefly verify that claim if cheap (e.g. revert the fix line, watch it fail, restore). 3. Run the relevant test suite; compare against the pre-existing failures you recorded. New failures are yours to explain. 4. `git status` / `git diff --stat`: only intended files changed; the user's pre-existing dirty files are untouched. ## Report Keep it short and evidence-backed: ``` **Symptom**: <expected vs actual, one line> **Reproducer**: `<command>` → <observed failing output, trimmed> **Root cause**: <what, where (file:line), and the observation that confirmed it> **Ruled out**: <hypotheses + the evidence against them> **Fix**: <files/lines changed and why this is the minimal change> **Verification**: reproducer now → <output>; regression test <name> (fails before / passes after); suite: <N pass, pre-existing failures: …> **Not done / open**: <blocked checks, missing prerequisites, follow-ups> ``` If the cause is environmental (wrong runtime, missing service, stale build), say so and give the corrective step for the user rather than patching code. If reproduction was blocked, lead with that and mark every cause as a hypothesis.