Debug with evidence
Find the cause of the reported failure, not a change that hides it. A request to
diagnose allows inspection only; a request to fix also allows a local fix and its
verification. When /work sent you here, stop at Ready to fix and return the
cause and the proposed fix. Never deploy, experiment on production, or replay
requests with real side effects without permission, and keep credentials out of
logs and shared output.
1. Reproduce
Ask the reporter in one message, at the latest with your diagnosis, for the
facts only they hold that change the next check or the remedy (what exactly
they saw, when, who was affected, what they already did about it), and never
propose a remedy, such as a refund, without asking whether it was done. Build
the smallest check that reaches the real failure: a test, a command, a request, or a
browser interaction that asserts the reported outcome. Record its output before
changing anything.
- Intermittent: count failures over attempts under controlled conditions
(seed, time, ordering) instead of retrying until it passes.
- Performance: fix the metric and workload, and measure repeated baseline
runs before profiling.
- No reproduction: reason from traces, logs, and code with explicitly
provisional hypotheses, and ask for the smallest missing capture or access.
2. Find the cause
For each plausible cause, state what it predicts and
run the cheapest check that could rule it out, changing one thing at a time.
Recent changes are leads, not proof; bisect only with a trustworthy good and bad
state, in a separate checkout. When checks stop teaching you anything, report what is
ruled out and the evidence still needed instead of stacking speculative patches.
Ready to fix: evidence connects the trigger, the faulty behavior, and the
symptom. A diagnosis-only request stops here with the cause and a proposed fix.
3. Fix and verify
- Capture the failure in a regression test before the fix and watch it fail for
the right reason. If no automated check is feasible, keep the reproducer and
say so.
- Do not mask the failure with sleeps, broad catches, retries, or fallbacks.
- Rerun the original scenario; compare failure counts or measurements under the
baseline's conditions for intermittent and performance problems.
- Remove your temporary probes.
Report the result as diagnosed, mitigated, or fixed-and-verified.
1---2name: debug3description: Use when asked to debug, diagnose, or fix a bug, failing test, crash, unexpected behavior, or performance regression whose cause is not established, or when /work routes a bug here.4metadata:5 source: https://skillmd.com/skills/firzus/debug6---78# Debug with evidence910Find the cause of the reported failure, not a change that hides it. A request to11diagnose allows inspection only; a request to fix also allows a local fix and its12verification. When `/work` sent you here, stop at **Ready to fix** and return the13cause and the proposed fix. Never deploy, experiment on production, or replay14requests with real side effects without permission, and keep credentials out of15logs and shared output.1617## 1. Reproduce1819Ask the reporter in one message, at the latest with your diagnosis, for the20facts only they hold that change the next check or the remedy (what exactly21they saw, when, who was affected, what they already did about it), and never22propose a remedy, such as a refund, without asking whether it was done. Build23the smallest check that reaches the real failure: a test, a command, a request, or a24browser interaction that asserts the reported outcome. Record its output before25changing anything.2627- **Intermittent:** count failures over attempts under controlled conditions28 (seed, time, ordering) instead of retrying until it passes.29- **Performance:** fix the metric and workload, and measure repeated baseline30 runs before profiling.31- **No reproduction:** reason from traces, logs, and code with explicitly32 provisional hypotheses, and ask for the smallest missing capture or access.3334## 2. Find the cause3536For each plausible cause, state what it predicts and37run the cheapest check that could rule it out, changing one thing at a time.38Recent changes are leads, not proof; bisect only with a trustworthy good and bad39state, in a separate checkout. When checks stop teaching you anything, report what is40ruled out and the evidence still needed instead of stacking speculative patches.4142**Ready to fix:** evidence connects the trigger, the faulty behavior, and the43symptom. A diagnosis-only request stops here with the cause and a proposed fix.4445## 3. Fix and verify46471. Capture the failure in a regression test before the fix and watch it fail for48 the right reason. If no automated check is feasible, keep the reproducer and49 say so.502. Do not mask the failure with sleeps, broad catches, retries, or fallbacks.513. Rerun the original scenario; compare failure counts or measurements under the52 baseline's conditions for intermittent and performance problems.534. Remove your temporary probes.5455Report the result as diagnosed, mitigated, or fixed-and-verified.