deniz-process.systematic-debugging
Use when encountering any bug, test failure, performance regression, or unexpected behavior, before proposing fixes
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- deniz-process.systematic-debugging
- description
- Use when encountering any bug, test failure, performance regression, or unexpected behavior, before proposing fixes
02 资源文件 5
- 脚本condition-based-waiting-example.ts4.9 KB
- 参考文档condition-based-waiting.md3.4 KB
- 参考文档defense-in-depth.md3.6 KB
- 脚本find-polluter.sh1.9 KB
- 参考文档root-cause-tracing.md5.2 KB
03 SKILL.md 正文
Systematic Debugging
Overview
Core principle: build a feedback loop, then find the root cause — no fixes before both. Symptom fixes are failure. A tight pass/fail signal for the bug is what bisection, hypotheses, and instrumentation all consume; without one, no amount of staring at code will save you.
Violating the letter of this process is violating the spirit of debugging.
The Iron Law
NO FIXES WITHOUT A RED FEEDBACK LOOP AND A ROOT CAUSE
If you haven't completed Phases 1–3, you cannot propose fixes.
When to Use
Use for ANY technical issue: test failures, bugs in production, unexpected behavior, performance regressions, build failures, integration issues.
Use this ESPECIALLY when:
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- The previous fix didn't work
- You don't fully understand the issue
Don't skip when: the issue seems simple (simple bugs have root causes too), you're in a hurry (systematic is faster than thrashing), or someone wants it fixed NOW.
Redact
This skill has you show commands, outputs and captured artifacts. Redact every secret first:
write <REDACTED> in its place. Build loops against env vars, so the credential stays in the
environment rather than in what you show. Captured artifacts carry auth headers: quote only the
lines that carry the signal.
If the redacted output is not enough to diagnose the bug, say so and ask your human partner.
Phase 1 — Build a Feedback Loop
This is the skill. Everything else is mechanical. If you have a tight pass/fail signal that goes red on this bug, you will find the cause. If you don't, stop — build one first.
Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.
Ways to construct one — in roughly this order
- Failing test at whatever seam reaches the bug — unit, integration, e2e.
- Curl / HTTP script against a running dev server.
- CLI invocation with a fixture input, diffing stdout against a known-good snapshot.
- Headless browser script (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
- Replay a captured trace. Save a real request / payload / event log to disk; replay it through the code path in isolation.
- Throwaway harness. Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single call.
- Property / fuzz loop. If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
- Bisection harness. If the bug appeared between two known states (commit, dataset,
version), automate "boot at state X, check, repeat" so you can
git bisect runit. - Differential loop. Run the same input through old vs new version (or two configs) and diff outputs.
- Human-in-the-loop script. Last resort. If a human must click, drive them with a structured checklist script whose captured output feeds back to you — still a loop, just a slow one.
Tighten the loop
Treat the loop as a product:
- Faster — cache setup, skip unrelated init, narrow the scope.
- Sharper — assert on the specific symptom, not "didn't crash".
- More deterministic — pin time, seed RNG, isolate filesystem, freeze network.
A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a debugging superpower.
Non-deterministic bugs
The goal is not a clean repro but a higher reproduction rate. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake is debuggable; 1% is not — keep raising the rate until it is.
When you genuinely cannot build a loop
Stop and say so explicitly. List what you tried. Ask your human partner for (a) access to the environment that reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, recording with timestamps), or (c) permission to add temporary production instrumentation. Do not proceed to hypothesise without a loop.
Completion criterion — one command that goes red
Phase 1 is done when you can name one command — a script path, a test invocation, a curl — that you have already run at least once (show the invocation and its output, redacted), and that 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.
- [ ] Deterministic — same verdict every run (flaky bugs: a pinned, high reproduction rate).
- [ ] Fast — seconds, not minutes.
- [ ] Agent-runnable — you can run it unattended.
If you catch yourself reading code to build a theory before this command exists, stop — jumping straight to a hypothesis is the exact failure this skill prevents.
Phase 2 — Reproduce and Minimise
Run the loop. Watch it go red. Confirm:
- [ ] The failure is the one the user described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
- [ ] It reproduces across multiple runs (or at a high enough rate to debug against).
- [ ] You captured the exact symptom (error message, wrong output, timing) so later phases can verify the fix addresses it.
Then shrink the repro to the smallest scenario that still goes red: cut inputs, callers, config, data, and steps one at a time, re-running the loop after each cut. Done when every remaining element is load-bearing — removing any one makes the loop go green. A minimal repro shrinks the hypothesis space and becomes the regression test later.
Phase 3 — Investigate the Root Cause
Before forming any hypothesis:
- Read error messages carefully. Complete stack traces, line numbers, error codes — they often contain the exact answer.
- Check recent changes. Git diff, recent commits, new dependencies, config changes, environmental differences.
- Gather evidence in multi-component systems. When the path crosses components (CI → build → signing, API → service → database), instrument each boundary — log what enters and exits, verify config propagation — and run once to see WHERE it breaks before asking why.
- Trace data flow. Where does the bad value originate? What called this with it? Keep
tracing up to the source — see
root-cause-tracing.mdin this directory. Fix at the source, not at the symptom. - Find the pattern. Locate similar working code in the same codebase; if implementing a reference pattern, read it COMPLETELY. List every difference between working and broken, however small — don't assume "that can't matter".
Phase 4 — Hypothesise and Test
Generate 3–5 ranked hypotheses before testing any. Single-hypothesis generation anchors on the first plausible idea.
Each hypothesis must be falsifiable — state its prediction:
"If <X> is the cause, then <changing Y> will make the loop go green / <changing Z> will make it worse."
If you cannot state the prediction, it's a vibe — discard or sharpen it.
Show the ranked list to your human partner before testing. They often re-rank instantly ("we just deployed a change to #3") or have already ruled some out. Don't block on it — proceed with your ranking if they're away.
Test minimally: the smallest possible change, one variable at a time. Didn't work? Form a NEW hypothesis — don't stack fixes. Don't know? Say "I don't understand X" and investigate — never pretend to know.
Phase 5 — Instrument
Each probe must map to a specific prediction from Phase 4. Change one variable at a time.
- Debugger / REPL inspection if the environment supports it — one breakpoint beats ten logs.
- Targeted logs at the boundaries that distinguish hypotheses.
- Never "log everything and grep".
Tag every debug log with a unique prefix, e.g. [DEBUG-a4f2] — cleanup becomes a single
grep. Untagged logs survive; tagged logs die.
Performance regressions: logs are usually the wrong tool. Establish a baseline measurement (timing harness, profiler, query plan), then bisect. Measure first, fix second.
Phase 6 — Fix
-
Regression test first — at a correct seam. Turn the minimised repro into a failing test using the deniz-process.test-driven-development skill. A correct seam exercises the real bug pattern as it occurs at the call site; a too-shallow seam gives false confidence. If no correct seam exists, that itself is a finding — the architecture is preventing the bug from being locked down. Document it and raise it with your human partner. If you forced the red by mutating code or a fixture,
diffagainst a pristine copy to prove the mutation landed before you trust it. -
Implement a single fix at the root cause. ONE change; no "while I'm here" improvements, no bundled refactoring.
-
Verify. Test passes, no other tests broken, and the Phase 1 loop goes green against the original (un-minimised) scenario. Use the deniz-process.verification-before-completion skill before claiming success.
-
If the fix doesn't work: STOP and count. Fewer than 3 attempts → return to Phase 3 with the new information. 3 or more → question the architecture:
Each fix revealing a new problem elsewhere, fixes needing "massive refactoring", every fix creating new symptoms — that pattern is not a failed hypothesis, it is a wrong architecture. Stop fix attempts on this bug before fix #4. Finish independent work, then bring the architecture question to your human partner with the evidence and your recommendation.
Phase 7 — Cleanup and Post-Mortem
Required before declaring done:
- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
- [ ] Regression test passes (or the absence of a correct seam is documented)
- [ ] All
[DEBUG-...]instrumentation removed (grep the prefix) - [ ] Throwaway harnesses and prototypes deleted
- [ ] The hypothesis that turned out correct is stated in the commit message — the next debugger learns from it
Then ask: what would have prevented this bug? If the answer is architectural (no good test
seam, tangled callers, hidden coupling), raise it with your human partner as its own piece of
work — after the fix is in, when you know the most. See defense-in-depth.md for adding
validation at multiple layers once the root cause is known.
If systematic investigation reveals the issue is truly environmental or external: document what you investigated, implement appropriate handling (retry, timeout, error message), add monitoring. But 95% of "no root cause" cases are incomplete investigation.
Red Flags — STOP and Follow the Process
If you catch yourself thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see if it works"
- Reading code to build a theory before a red-capable command exists
- "Add multiple changes, run tests"
- "Skip the test, I'll manually verify"
- "It's probably X, let me fix that"
- "I don't fully understand but this might work"
- Proposing solutions before tracing data flow
- "One more fix attempt" (when already tried 2+)
- Each fix reveals a new problem in a different place
ALL of these mean: STOP. Return to the phase you skipped.
Common Rationalizations
| Excuse | Reality |
|---|---|
| "Issue is simple, don't need process" | Simple issues have root causes too. The process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
| "A loop is overkill, I can eyeball this" | Without a red signal you cannot even prove the bug is fixed. |
| "Just try this first, then investigate" | The first fix sets the pattern. Do it right from the start. |
| "I'll write the test after confirming the fix" | Untested fixes don't stick. Red first proves the test can catch it. |
| "Multiple fixes at once saves time" | You can't isolate what worked, and it causes new bugs. |
| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding the root cause. |
| "One more fix attempt" (after 2+) | 3+ failures = architectural problem. Question the pattern, don't fix again. |
Quick Reference
| Phase | Key activity | Done when |
|---|---|---|
| 1. Loop | Construct a tight pass/fail signal | One red-capable, deterministic, fast command — already run |
| 2. Reproduce + minimise | Watch it go red, shrink the repro | Every remaining element is load-bearing |
| 3. Root cause | Errors, recent changes, evidence, data flow, patterns | You understand WHAT and WHY |
| 4. Hypothesise | 3–5 ranked, falsifiable predictions | One confirmed by minimal test |
| 5. Instrument | One probe per prediction, tagged | Hypotheses distinguished by evidence |
| 6. Fix | Test-first at a correct seam, single fix | Test green, suite green, loop green |
| 7. Cleanup | Remove instrumentation, post-mortem | Checklist above complete |
Supporting Techniques
Available in this directory:
root-cause-tracing.md— trace bugs backward through the call stack to the original triggerdefense-in-depth.md— add validation at multiple layers after finding the root causecondition-based-waiting.md— replace arbitrary timeouts with condition polling
04 同仓库更多 Skills
writing-tunit-tests
Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.
dotnet-walls
Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.
csharp-15
Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.
verified-waves
Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.
harness
The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.
delegating-to-worker-models
Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.