dx-diagnose
Skill8 starsChanged 4 months agoMITView on GitHub
Feedback-loop-first diagnosis for bugs and performance regressions. Use when something misbehaves (errors, crashes, hangs, wrong output), got slower or flaky, or regressed — or when the user asks to debug or find the root cause of a defect or perf problem.
In this repository21 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- dx-archiveSkill
- dx-brainstormSkill
- dx-distillSkill
- dx-domain-discoverSkill
- dx-domainSkill
- dx-frameSkill
- dx-implementSkill
- dx-initSkill
- dx-lessonSkill
- dx-newSkill
- dx-planSkill
- dx-refactor-discoverSkill
- dx-referencesSkill
- dx-researchSkill
- dx-reviewSkill
- dx-review-triageSkill
- dx-roadmapSkill
- dx-standards-discoverSkill
- dx-standards-updateSkill
- dx-tddSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
Run the loop red. Confirm it is the user's symptom, not a nearby one.
- Distinctive: line 55
Never chain into the next skill.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
dx-diagnose
Find the cause of a bug or perf regression, then either fix it inline or promote it into a change. Feedback-loop-first: no red-capable loop, no hypothesising. Read foundation/glossary.md if present (one-line habit — name the symptom in the project's terms).
Ad-hoc by default: this runs on a raw symptom with no container. If invoked mid-task (e.g. during /dx-implement), finish diagnosing this bug, then suggest the next step — don't silently resume the interrupted skill.
Phase 1 — Build a tight, red-capable loop (this is the skill)
Name one command — a failing test, curl, CLI diff, headless-browser script, trace replay, throwaway harness, fuzz/property loop, git bisect run, or differential run — that you have already run once (paste invocation + output) and that:
- goes red on THIS bug — drives the real code path and asserts the user's exact symptom (not "runs without erroring");
- is deterministic (flaky bugs: raise the reproduction rate until debuggable) and fast (seconds).
Spend your effort here — once a tight loop exists, most of the fix follows. If you genuinely cannot build one, stop and say so — list what you tried, ask for an environment/artifact/instrumentation. Done when that command exists and goes red. Catching yourself theorising before it exists is the exact failure this prevents.
Phase 2 — Reproduce + minimise
Run the loop red. Confirm it is the user's symptom, not a nearby one. Then shrink to the smallest scenario that still goes red — cut inputs/callers/config one at a time, re-running each cut. Done when every remaining element is load-bearing.
Phase 3 — Hypothesise (3–5, ranked, falsifiable)
Generate 3–5 hypotheses before testing any — single-hypothesis anchors on the first plausible idea. Each states its prediction: "if X is the cause, changing Y flips the verdict." No prediction → it's a vibe; sharpen or drop it. Show the ranked list to the user before instrumenting (they may re-rank instantly); proceed on your ranking if they're AFK.
Phase 4 — Instrument (one variable at a time)
Each probe maps to one Phase-3 prediction. Prefer a debugger/REPL over logs; tag every debug log with a unique prefix ([DEBUG-a4f2]) so cleanup is one grep. For perf: measure a baseline first (profiler / timing / query plan), then bisect — never "log everything".
Phase 5 — Fix + regression test
Write the regression test first if a correct seam exists — one exercising the real bug pattern at its call site. If the only seam is too shallow to catch it, that absence is itself the finding — note it. Fix, watch red→green, then re-run the Phase 1 loop against the original un-minimised scenario.
Phase 6 — Cleanup + outcome
Original repro gone, regression test green (or missing-seam documented), all [DEBUG-…] removed, throwaway harnesses deleted. State the winning hypothesis. Then decide:
- Trivial → ad-hoc, no container. Fix stays inline, regression test stays. No artifacts. Never auto-rollback.
- Non-trivial → PROMOTE. Write
diagnosis.md(minimised repro + ranked hypotheses + regression test) and run/dx-newstampedtype: defect(which activates the TDD gate in/dx-plan), carrying that file as the change's seed. For the change's schema, invokedx-referenceswith topicchange-md./dx-planreadsdiagnosis.mdthe way it reads research.
Done when
Print the outcome and the next command, then stop:
Trivial: Fixed inline: <one-line cause>. Regression test: <path>.
Promoted: Diagnosis written: context/changes/<id>/diagnosis.md
Next: /dx-plan <id> (defect → TDD gate)Never chain into the next skill; never roll back without the user.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

