メニュー
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
Recurring maintenance pass over automated dependency-bump PRs (Dependabot, Renovate, or similar) — rebase, relock, verify, and report what's ready to merge. Meant to be handed to a time-based loop or schedule, not run once.
Post-deploy verification loop — poll a rollout until every instance is on the new version and healthy, then run one smoke check against a real user path. Meant to be handed to a time-based loop with a timeout, not polled by hand.
Reference for designing agent loops — cycles of work that repeat until a stop condition is met. Covers the four loop shapes, writing completion criteria, carrying state and isolating work across cycles, and what running unattended still leaves on you.
Recurring check-in on a stack of dependent PRs — rebase children onto updated parents, surface CI state, flag anything waiting on a human-only gate, and report only what changed since last time. Meant to be handed to a time-based loop, not run once.
Pick the skill or flow that fits your situation. A router over the skills in this repo.
Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
| name | diagnosing-bugs |
| description | Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow. |
A discipline for the hard ones. Skip a phase only when you can explicitly justify it.
While you're getting your bearings, read CONTEXT.md (if it exists) to build a clean mental model of the modules in play, and check any ADRs covering the area you're touching.
This is the skill. Everything downstream is mechanical. Give yourself a tight pass/fail signal — one that goes red on this specific bug — and you will find the cause; bisection, hypothesis-testing, and instrumentation are just ways of spending that signal. Without one, no amount of staring at code will rescue you.
Pour disproportionate effort in here. Be aggressive. Be creative. Refuse to give up.
git bisect run can drive it.scripts/hitl-loop.template.sh so the loop stays structured. What they report flows back to you.Build the right feedback loop and the bug is 90% solved.
Treat the loop as a product. Once you have any loop, tighten it:
A 30-second flaky loop barely beats no loop; a 2-second deterministic one is tight — a debugging superpower.
The target isn't a clean repro but a higher reproduction rate. Loop the trigger 100×, parallelise, pile on stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; a 1% one isn't — keep pushing the rate up until it is.
Stop and say so, out loud. List what you tried. Ask the user for one of: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, timestamped screen recording), or (c) permission to add temporary production instrumentation. Do not roll on to hypothesising without a loop.
Phase 1 is done when the loop is tight and red-capable: you can name one command — a script path, a test invocation, a curl — that you have already run at least once (paste the invocation and its output), and that is:
scripts/hitl-loop.template.sh.If you catch yourself reading code to form a theory before this command exists, stop — leaping straight to a hypothesis is the exact failure this skill exists to prevent. No red-capable command, no Phase 2.
Run the loop. Watch it go red — the bug surfaces.
Confirm:
Now that it's red, shrink the repro to the smallest scenario that still goes red. Strip inputs, callers, config, data, and steps one at a time, re-running the loop after each cut — keep only what's load-bearing for the failure.
Why: a minimal repro collapses the hypothesis space in Phase 3 (fewer parts left to suspect) and becomes the clean regression test in Phase 5.
Done when every remaining element is load-bearing — pulling any one of them makes the loop go green.
Don't move on until you've both reproduced and minimised.
Produce 3–5 ranked hypotheses before testing any of them. Generating a single hypothesis anchors you on the first plausible idea.
Each hypothesis must be falsifiable: state the prediction it makes.
Format: "If is the cause, then will make the bug vanish / will make it worse."
If you can't state the prediction, the hypothesis is a vibe — sharpen it or drop it.
Show the ranked list to the user before testing. They often carry domain knowledge that re-ranks it instantly ("we just shipped a change to #3"), or know which ones they've already ruled out. Cheap checkpoint, huge time saver. Don't block on it — go with your own ranking if the user is AFK.
Each probe maps to a specific prediction from Phase 3. Change one variable at a time.
Tool preference:
Tag every debug log with a unique prefix, e.g. [DEBUG-a4f2]. Cleanup at the end is then a single grep. Untagged logs linger; tagged logs die.
Perf branch. For performance regressions, logs are usually the wrong tool. Instead: take a baseline measurement (timing harness, performance.now(), profiler, query plan), then bisect. Measure first, fix second.
Write the regression test before the fix — but only when a correct seam exists for it.
A correct seam is one where the test drives the real bug pattern as it happens at the call site. If the only seam available is too shallow (a single-caller test when the bug needs multiple callers, a unit test that can't reproduce the chain that triggered it), a regression test there hands you false confidence.
If no correct seam exists, that's itself the finding. Note it. The codebase architecture is blocking the bug from being locked down. Flag it for the next phase.
If a correct seam exists:
Required before you call it done:
[DEBUG-...] probe removed (grep the prefix)Then ask: what would have stopped this bug from happening? If the answer involves an architectural change (no good test seam, tangled callers, hidden coupling), hand off to the /improve-codebase-architecture skill with the specifics. Make that recommendation after the fix lands, not before — you know far more now than when you started.