3314257466
aihero.dev renders an install widget above every skill page. Each page then repeated the same commands in its body, and the two copies had drifted: the widget uses the current `npx skills@latest ...` wording while the hand-written blocks mostly carried the older bare `npx skills ...`. Pages showed the right command and a stale one together. Delete the block from all 25 pages and record the rule in .agents/writing-docs.md: install wording belongs to the site, not the page. The template no longer carries a Quickstart, and .agents/install-block.md notes that docs pages are not one of its consumers.
2.8 KiB
What it does
diagnosing-bugs runs a disciplined diagnosis loop for hard bugs and performance regressions — building a repro, minimising it, ranking hypotheses, instrumenting, then fixing with a regression test.
It refuses to hypothesise before you have a tight feedback loop — one runnable command that already goes red on this bug. Reading code to build a theory before that command exists is the exact failure this skill prevents. No red-capable loop, no diagnosis.
When to reach for it
Type /diagnosing-bugs, or the agent reaches for it automatically when a task fits — it fires on "diagnose" / "debug this", or when you report something broken, throwing, failing, or slow.
Reach for it on the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. For a quick throwaway to sanity-check a design question rather than chase a defect, use prototype instead.
The tight loop is the skill
Everything else — bisection, hypothesis-testing, instrumentation — is mechanical once you have the signal. So the skill spends disproportionate effort on Phase 1: constructing a pass/fail command that drives the actual bug code path and asserts the user's exact symptom, then tightening it until it is fast, deterministic, and agent-runnable. A 30-second flaky loop is barely better than none; a 2-second deterministic one is a debugging superpower.
It gives you a ladder of ways to build that loop — failing test, curl script, CLI diff, headless browser, replayed trace, throwaway harness, fuzz loop, git bisect run, differential run — and, only as a last resort, a human-in-the-loop bash script. For non-deterministic bugs the goal isn't a clean repro but a higher reproduction rate: loop the trigger, parallelise, add stress until the flake is debuggable.
It's working if
- It builds and runs a repro command before theorising — and pastes the invocation and its red output.
- The loop asserts the symptom you actually reported, not a nearby failure.
- Hypotheses arrive as a ranked, falsifiable list shown to you before any are tested.
- Debug instrumentation is tagged (
[DEBUG-...]) and grepped away before it declares done.
Where it fits
diagnosing-bugs is a reach-for-it-anytime standalone — you drop into it the moment something is broken, and drop out once the fix and its regression test are in. Its post-mortem hands off to improve-codebase-architecture when the real finding is that there's no good seam to lock the bug down — the code, not the bug, is the problem. When you're unsure which skill fits, ask-matt routes you.