When you explore the codebase, read GLOSSARY.md if it exists. It gives a clear mental model of the relevant modules. Also check the ADRs in the area you touch.
If the redacted output is not enough to diagnose the bug, say so and ask the user.
Most of the effort in a hard bug belongs here.
A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is tight.
Read the code you need to build this command, and hold theories about the cause until it exists. Without a red-capable command, Phase 2 does not start.
Once the loop is red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps one at a time. Re-run the loop after each cut, and keep only what carries the failure. A minimal repro shrinks the hypothesis space in Phase 3, because fewer moving parts remain to suspect. It also becomes the clean regression test in Phase 5.
Minimising is done when every remaining element carries the failure. Removing any one of them then makes the loop go green. Stop earlier when further cuts would not change the fix.
Each hypothesis must be falsifiable, so state the prediction it makes. Write it in the form "If X is the cause, then changing Y will make the bug disappear, or changing Z will make it worse." If you cannot state the prediction, the hypothesis is a vibe, so discard or sharpen it.
When the ranking is uncertain and the user is present, show it in a sentence or two before you test it. The user often has domain knowledge that re-ranks the list at once, as in "we just deployed a change to #3", and may know hypotheses they already ruled out. Do not block on it, and proceed with your ranking if the user is away.
The tools come in this order of preference.
- Debugger or REPL inspection, if the environment supports it. One breakpoint beats ten logs.
- Targeted logs at the boundaries that distinguish the hypotheses.
- Never "log everything and grep".
Tag every debug log with a unique prefix, such as [DEBUG-a4f2]. Cleanup at the end then becomes a single grep. Untagged logs survive, and tagged logs get removed.
Performance regressions need a different approach, because logs are usually wrong for them. Establish a baseline measurement first, with a timing harness, performance.now(), a profiler, or a query plan. Then bisect. Measure first, and fix second.
A correct seam is one where the test exercises the real bug pattern as it occurs at the call site. The only available seam may be too shallow. For example, a single-caller test cannot catch a bug that needs multiple callers. A unit test also cannot replicate the chain that triggered the bug. A regression test at such a seam gives false confidence.
If no correct seam exists, that itself is the finding. The codebase architecture prevents the bug from being locked down, so tell the user in the report.
If a correct seam exists, follow these steps.
- Turn the minimised repro into a failing test at that seam.
- Watch it fail. If you forced the red by mutating code or a fixture,
diff against a pristine copy. This proves the mutation landed before you trust it.
- Apply the fix.
- Watch the test pass.
- Re-run the Phase 1 feedback loop against the original, un-minimised scenario.
1---2name: debugging3description: Diagnosis loop for anything reported broken, throwing, failing, flaky, slow, or giving wrong output, including a user's report that a feature or page stopped working. Use it whenever such a report arrives and the cause is not yet proven by the error and the code it points to, before you change code to fix it, even when the first explanation looks obvious.4metadata:5 source: https://skillmd.com/skills/dayfinggg/debugging6---78<overview>9This is a discipline for hard bugs. A fault whose cause the error already shows needs only the `debugging` block of the coding instructions. Skip a phase of this skill only when you can name the reason.1011When you explore the codebase, read `GLOSSARY.md` if it exists. It gives a clear mental model of the relevant modules. Also check the ADRs in the area you touch.12</overview>1314<redact>15This skill has you show commands, outputs, and captured artifacts. Redact every secret first, and write `<REDACTED>` in its place. Build loops against environment variables, so the credential stays in the environment and out of what you show. Captured artifacts carry auth headers, so quote only the lines that carry the signal.1617If the redacted output is not enough to diagnose the bug, say so and ask the user.18</redact>1920<phase_1_feedback_loop>21The feedback loop is the skill, and everything else is mechanical. A tight pass or fail signal goes red on this specific bug. With such a signal, you will find the cause. Bisection, hypothesis testing, and instrumentation all just consume it. Without one, no amount of staring at code will save you.2223Most of the effort in a hard bug belongs here.2425<ways_to_build_a_loop>26These ways to construct a loop come in roughly this order of preference.271. A failing test at whatever seam reaches the bug, such as unit, integration, or e2e.282. A curl or HTTP script against a running dev server.293. A CLI invocation with a fixture input, diffing stdout against a known-good snapshot.304. A headless browser script (Playwright or Puppeteer) that drives the UI and asserts on DOM, console, or network.315. A replay of a captured trace. Save a real network request, payload, or event log to disk. Then replay it through the code path in isolation.326. A throwaway harness. Spin up a minimal subset of the system, such as one service with mocked dependencies. It exercises the bug code path with a single function call.337. A property or fuzz loop. If the bug is "sometimes wrong output", run many random inputs and look for the failure mode.348. A bisection harness. If the bug appeared between two known states, such as commits, datasets, or versions, automate the check. The harness boots at state X, checks, and repeats, so you can `git bisect run` it.359. A differential loop. Run the same input through the old and new version, or through two configs, and diff the outputs.3610. A HITL bash script, as the last resort. If a human must click, drive them with `scripts/hitl-loop.template.sh` so the loop stays structured. Its captured output feeds back to you.37</ways_to_build_a_loop>3839<hitl_script>40`scripts/hitl-loop.template.sh` is a human-in-the-loop reproduction loop. Copy it, and replace its `step` and `capture` lines and the matching `printf` lines. Give the user the `bash` command that runs it, because it reads answers from the keyboard and needs their terminal. `step "<instruction>"` shows an instruction and waits for Enter. `capture VAR "<question>"` shows a question and reads the answer into VAR. At the end, the script prints the captured values as KEY=VALUE lines, and the user passes that output back to you. Every captured value appears in that output, so capture only observations, and leave signing in to the user as a `step`.41</hitl_script>4243<tighten_the_loop>44Treat the loop as a product. Once you have a loop, tighten it with these questions.45- Can I make it faster? Cache setup, skip unrelated init, and narrow the test scope.46- Can I make the signal sharper? Assert on the specific symptom, not on "didn't crash".47- Can I make it more deterministic? Pin time, seed the RNG, isolate the filesystem, and freeze the network.4849A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is tight.50</tighten_the_loop>5152<non_deterministic_bugs>53For a non-deterministic bug, the goal is a higher reproduction rate, not a clean repro. Loop the trigger many times, parallelise, add stress, narrow timing windows, and inject sleeps. A bug that fails 50 percent of the time is debuggable, and a 1 percent bug is not. Keep raising the rate until the bug is debuggable.54</non_deterministic_bugs>5556<no_loop_possible>57When you cannot build a loop, stop and say so explicitly. List what you tried. Ask the user for one of these things.58- Access to an environment that reproduces the bug.59- A redacted captured artifact, such as a HAR file, log dump, core dump, or screen recording with timestamps.60- Permission to add temporary production instrumentation.61</no_loop_possible>6263<phase_1_done>64Phase 1 is done when the loop is tight and red-capable. You can name one command, such as a script path, a test invocation, or a curl. You have already run it at least once, and you show the invocation and its redacted output. The command meets each condition in this checklist.65- [ ] It is red-capable. It drives the actual bug code path and asserts the user's exact symptom. So it goes red on this bug and green once fixed. "Runs without erroring" is not enough, because the command must catch this specific bug.66- [ ] It is deterministic, with the same verdict every run. For a flaky bug, it has a pinned, high reproduction rate.67- [ ] It is fast, taking seconds and not minutes.68- [ ] It is agent-runnable, so you can run it unattended. A human joins the loop only through `scripts/hitl-loop.template.sh`.6970Read the code you need to build this command, and hold theories about the cause until it exists. Without a red-capable command, Phase 2 does not start.71</phase_1_done>72</phase_1_feedback_loop>7374<phase_2_reproduce_and_minimise>75Run the loop, and watch it go red as the bug appears. Then confirm each item in this checklist.76- [ ] The loop produces the failure mode the user described, not a different failure nearby. The wrong bug leads to the wrong fix.77- [ ] The failure reproduces across multiple runs. A non-deterministic bug reproduces at a rate high enough to debug against.78- [ ] You captured the exact symptom, such as an error message, wrong output, or slow timing. Later phases use it to verify the fix.7980Once the loop is red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps one at a time. Re-run the loop after each cut, and keep only what carries the failure. A minimal repro shrinks the hypothesis space in Phase 3, because fewer moving parts remain to suspect. It also becomes the clean regression test in Phase 5.8182Minimising is done when every remaining element carries the failure. Removing any one of them then makes the loop go green. Stop earlier when further cuts would not change the fix.83</phase_2_reproduce_and_minimise>8485<phase_3_hypothesise>86Before you test anything, list the hypotheses the evidence still allows and rank them, because a single hypothesis anchors on the first plausible idea. When the evidence already isolates one cause, test that one.8788Each hypothesis must be falsifiable, so state the prediction it makes. Write it in the form "If X is the cause, then changing Y will make the bug disappear, or changing Z will make it worse." If you cannot state the prediction, the hypothesis is a vibe, so discard or sharpen it.8990When the ranking is uncertain and the user is present, show it in a sentence or two before you test it. The user often has domain knowledge that re-ranks the list at once, as in "we just deployed a change to #3", and may know hypotheses they already ruled out. Do not block on it, and proceed with your ranking if the user is away.91</phase_3_hypothesise>9293<phase_4_instrument>94Each probe maps to a specific prediction from Phase 3. Change one variable at a time.9596The tools come in this order of preference.971. Debugger or REPL inspection, if the environment supports it. One breakpoint beats ten logs.982. Targeted logs at the boundaries that distinguish the hypotheses.993. Never "log everything and grep".100101Tag every debug log with a unique prefix, such as `[DEBUG-a4f2]`. Cleanup at the end then becomes a single grep. Untagged logs survive, and tagged logs get removed.102103Performance regressions need a different approach, because logs are usually wrong for them. Establish a baseline measurement first, with a timing harness, `performance.now()`, a profiler, or a query plan. Then bisect. Measure first, and fix second.104</phase_4_instrument>105106<phase_5_fix_and_regression_test>107Write the regression test before the fix, but only if a correct seam exists for it.108109A correct seam is one where the test exercises the real bug pattern as it occurs at the call site. The only available seam may be too shallow. For example, a single-caller test cannot catch a bug that needs multiple callers. A unit test also cannot replicate the chain that triggered the bug. A regression test at such a seam gives false confidence.110111If no correct seam exists, that itself is the finding. The codebase architecture prevents the bug from being locked down, so tell the user in the report.112113If a correct seam exists, follow these steps.1141. Turn the minimised repro into a failing test at that seam.1152. Watch it fail. If you forced the red by mutating code or a fixture, `diff` against a pristine copy. This proves the mutation landed before you trust it.1163. Apply the fix.1174. Watch the test pass.1185. Re-run the Phase 1 feedback loop against the original, un-minimised scenario.119</phase_5_fix_and_regression_test>120121<phase_6_cleanup>122These items are required before you declare the bug done.123- [ ] The original repro no longer reproduces, after a re-run of the Phase 1 loop.124- [ ] The regression test passes, or the absence of a seam is documented.125- [ ] All `[DEBUG-...]` instrumentation is removed, after a `grep` for the prefix.126- [ ] Throwaway files are removed, as `code_rules` in the coding instructions requires.127- [ ] The report states the hypothesis that turned out correct. When the user asks for a commit or PR, its message states it too, so the next debugger learns it.128</phase_6_cleanup>