diagnose
Skill2 starsChanged 12 days agoMITView on GitHub
Find and fix the cause of a bug or a performance regression with a red feedback loop, ranked hypotheses and a regression test. Use when the user runs /diagnose, or /build picks it.
193 other projects use a version of this.
Adopted by
Most recently taken up by
- blauwtje/exotheir own version, first seen Nov 16, 2026
- Robo-Co-op/robobuilder-standardtheir own version, first seen Nov 16, 2026
- akshay-diwadkar/first-four-hourstheir own version, first seen Nov 16, 2026
- AshrafDurjoy/genai-shared-patternstheir own version, first seen Nov 16, 2026
- FAHTHIZ/oasistheir own version, first seen Nov 16, 2026
- timmo001/skillstheir own version, first seen Nov 15, 2026
Used with
Projects with it also use zoom-out, to-prd and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
victorgarciaesgiSkillzoom-out
Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
Also in 62 projects that use this
GoogleSkillto-prd
Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
Also in 58 projects that use this
GoogleSkillto-issues
Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.
Also in 54 projects that use this
simo97Skillwrite-a-skill
Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
Also in 46 projects that use this
simo97Skilledit-article
The user will invoke this skill to help them edit an article.
Also in 17 projects that use this
kennethkeimSkillubiquitous-language
Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
Also in 16 projects that use this
- +5 more from simo97
Other versions193 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 193
- github/awesome-copilot★ 41ksame name
- epicenter-md/epicenter★ 4.8ksame name
- EpicenterHQ/epicenter★ 4.8ksame name
- CherryHQ/cherry-studio-app★ 4.1ksame name
- pedrohcgs/claude-code-my-workflow★ 1.7ksame name
- formancehq/ledger★ 1.5ksame name
- getagentseal/founder-playbook★ 745same name
- victorgarciaesgi/regle★ 508same name
- amazingloft999-droid/mattpocock-skills★ 422same name
- openvetta/open-vetta★ 299same name
183 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository22 other files it gives its agents.
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. 0 are common, 14 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 175 edited versions we read keep these.
14
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
When /build runs this skill, skip the steps marked "(not under /build)".
- Distinctive: line 19
When you stop, put the symptom and the path of each attachment in the stop message, so that the next run needs no new input from the user.
- Very specific: line 25
Read the ## Agent skills block in AGENTS.md, then docs/agents/tracker.md.
- Very specific: line 33
Call the Skill tool with worktree for fix/<n>-<slug>, made from the trunk.
- Distinctive: line 58
When you cannot build a loop, stop.
- Distinctive: line 60
When the loop needs production facts, ask for all of them in one message.
- Distinctive: line 69
Before this command exists, read only the code that the loop calls.
- Very specific: line 73
Run the loop, and see it go red.
- Distinctive: line 81
Write 3 to 5 hypotheses, ranked.
- Very specific: line 89
Test one prediction at a time.
- Distinctive: line 93
When the user's pick is false, go to the next hypothesis in the ranking.
- Distinctive: line 95
When no offline loop can test the cause, the cause is not confirmed.
- Distinctive: line 106
Run it, and see it fail on the symptom.
- Distinctive: line 108
Run the test, and see it pass.
- Distinctive: line 109
Run the loop from step 3 on the original scenario.
- Distinctive: line 117
Search for the debug prefix with git grep.
- Distinctive: line 118
Run the loop from step 3 one more time.
- Distinctive: line 119
Delete each harness and script that the regression test replaces.
- Very specific: line 125
Run the typecheck, the lint, and the tests that the fix adds or touches.
- Distinctive: line 131
Write the card in your message, before the question.
- Very specific: line 143
Keep "Check yourself" to three steps or fewer.
“Common” is measured: kept by at least 6 in 10 of the 175 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Diagnose
/diagnose takes a bug from a symptom to one fix commit. The loop is the skill: one command that goes red on this bug and green when it is fixed. With a tight loop, the cause falls out of the steps that follow. With no loop, reading code gives only a guess.
When /build runs this skill, skip the steps marked "(not under /build)". /build owns them.
When you stop, put the symptom and the path of each attachment in the stop message, so that the next run needs no new input from the user.
After EnterWorktree, run one plain shell command per call, from the worktree root, on paths in the worktree. For a subfolder, use a flag such as pnpm --dir or uv --directory, because a cd stays in effect for the rest of the session. Change a file with the Edit tool, and make a new file with the Write tool. Quote each argument that holds *, [ or ]. The guard refuses only some other forms, such as a && chain, $(...) or a heredoc, so a command that ran is no proof that its form is safe.
1. Issue (not under /build)
Read the ## Agent skills block in AGENTS.md, then docs/agents/tracker.md. When the block is missing, read NO-SETUP.md in the folder of the setup-skills skill, and go on with its sources.
When the input is a Sentry link, an error or a screenshot, call the Skill tool with issue to create a bug issue, with its bug template and the bug label. Step 4 adds the exact symptom. When the input is an issue, read it. Its Where to look feeds the loop, and its Hypotheses to rank go into the ranking of step 5 with your own. Then set the issue to in progress, as tracker.md says.
Completion: the bug is an issue in progress, and you have its number, or the repo has no tracker and the report keeps the issue text.
2. Worktree (not under /build)
Call the Skill tool with worktree for fix/<n>-<slug>, made from the trunk. When it reports blocked, follow the Worktree line of NO-SETUP.md.
Completion: the session is in the fix worktree, or on the fix branch or the current branch as NO-SETUP.md says.
3. Loop
Read the glossary that docs/agents/domain.md names, or that NO-SETUP.md names. Open each ADR that the area's code or the glossary names. A listing of docs/adr/ is not a read. The fix keeps the meaning of each glossary term. Then build the loop. Try these in order:
- A failing test at the seam that reaches the bug.
- A
curlscript against a running dev server. - A CLI call with a fixture input, compared with a known-good output.
- A headless browser script that drives the UI and checks the DOM, the console or the network.
- A replay of a captured request, payload or event log through the code path.
- A throwaway harness: the smallest part of the system that runs the code path in one call.
- A fuzz loop: many random inputs, for output that is sometimes wrong.
- A bisect harness:
git bisect runbetween a good and a bad commit. - A differential loop: one input through the old and the new version, with the outputs compared.
- A human loop. Call the Skill tool with
ui-checkto show the bug in a browser first. For what a browser cannot do, ask the user with the question tool, one step for each question, and record each answer.
Then tighten it: make it faster, assert on the exact symptom, and pin the time, the random seed and the network.
For a bug that does not occur each time, raise the rate: run the trigger many times, in parallel, under load. A rate of 50% is enough to work with. A rate of 1% is not.
When the loop or the suite needs a workaround for a fault outside the bug, such as an env var that breaks the test setup, file the fault once. Call the Skill tool with issue, when no open issue names the fault. Name the workaround and the issue in the report.
When you cannot build a loop, stop. List what you tried. Ask the user for access to an environment that shows the bug, a captured artifact, or approval for temporary instrumentation in production.
When the loop needs production facts, ask for all of them in one message. Write each query against the schema of the deployed branch, and offer temporary instrumentation in the same question.
Completion: you read the glossary and the ADRs for the area. You have one command, and you ran it at least once. It is:
- Red: it runs the code path of the bug and asserts the user's exact symptom.
- Deterministic: each run gives the same result, or a pinned high rate.
- Fast: seconds, not minutes.
- Agent-run: you run it with no human, except through the human loop.
Before this command exists, read only the code that the loop calls.
4. Reproduce and minimise
Run the loop, and see it go red. Confirm that the failure is the user's symptom, not a different failure near it. Record the exact symptom. When step 1 created the issue, add the exact symptom, redacted, to its body, as tracker.md says.
Then cut one part at a time: inputs, callers, config, data and steps. Run the loop after each cut. Keep only the parts that the failure needs.
Completion: the loop is red on the user's symptom, and each part that is left makes the loop green when you remove it.
5. Hypothesise
Write 3 to 5 hypotheses, ranked. A hypothesis names a cause, not a fix. Each one states its prediction: "When <X> is the cause, <changing Y> makes the bug go away." A hypothesis with no prediction is a guess: sharpen it or remove it.
Ask with the question tool which hypothesis to test first. Give one option for each hypothesis, with its prediction in the description. An option holds one hypothesis only. Mark your top pick as recommended. When the question returns no answer, ask it again before any other action.
Completion: the user picked a hypothesis, or wrote their own.
6. Instrument
Test one prediction at a time. Change one variable at a time. Use a debugger when the environment has one. Otherwise, add logs at the boundaries that tell the hypotheses apart. Tag each debug log with one prefix, such as [DEBUG-a4f2].
For a performance bug, measure a baseline first, with a timer, a profiler or a query plan. Then bisect.
When the user's pick is false, go to the next hypothesis in the ranking.
When no offline loop can test the cause, the cause is not confirmed. The card says "cause not confirmed" and names the real-world check that confirms it.
Completion: one hypothesis is confirmed by its prediction, and the others that you tested are false, or the card will say "cause not confirmed" with its check.
7. Fix
Find a correct seam: a seam where a test runs the real pattern of the bug, as it occurs at the call site. A seam that is too shallow, such as one caller when the bug needs two, gives false confidence.
With a correct seam:
- Turn the minimised repro into a failing test at the seam.
- Run it, and see it fail on the symptom. When you forced the red with a change to the code, confirm with
git diffthat the change is there, and undo it after. - Fix the cause.
- Run the test, and see it pass.
- Run the loop from step 3 on the original scenario.
With no correct seam, fix the cause and record the missing seam. The architecture keeps this bug from a regression test, and the team needs to know.
Completion: the loop is green, and the regression test passes, or the missing seam is recorded.
8. Cleanup
- Search for the debug prefix with
git grep. Remove each hit. - Run the loop from step 3 one more time.
- Delete each harness and script that the regression test replaces. When the loop itself is a harness, move it out of the repo, such as to the scratchpad, and keep it until step 11.
Completion: git grep finds no debug prefix, the loop is green, and no throwaway file is left in the repo.
9. Check (not under /build)
Run the typecheck, the lint, and the tests that the fix adds or touches. /ship runs the one cold read and the full check.
Completion: each check passed after the last change.
10. Card (not under /build)
Write the card in your message, before the question. The question tool does not show it, and the user approves what they can read.
### #<n> <title>
Cause: <the confirmed hypothesis, in one sentence, or "cause not confirmed" and the check that confirms it>
Fix: <one sentence>
Test: <test name> | Missing seam: <why>
Check yourself: `<run command>`
1. <a step and what the user sees>Keep "Check yourself" to three steps or fewer. The card has only these parts. A finding outside the fix goes in the report, as an issue filed with issue.
Ask with the question tool: "Approve", "Change" or "Run ui-check". Leave out "Run ui-check" when it already ran on the fix. On Run ui-check, call the Skill tool with ui-check for this bug, then ask again with "Approve" or "Change". On Change, make the edits, commit, run the checks of step 9, and show the card again. When Change comes with no notes, ask in the chat what to change. A free-text answer that clearly approves counts as Approve. Only for a free-text answer, start the reply with: "Taking that as Approve." When the question returns no answer, ask it again before any other action.
Completion: the card is in the chat above the question, and the user approved. Stop the dev server, and close the tab as ui-check says, when ui-check started them.
11. Record
Squash the branch into one commit, except under /build, which squashes when it lands the ticket, and except for work that NO-SETUP.md keeps uncommitted. Run git merge-base HEAD origin/<trunk>, then git reset --soft <base>. Commit with -m "Fix <title> (#<n>)", then -m "Cause: <the confirmed hypothesis>". When the cause is not confirmed, the title is Instrument <symptom> (#<n>), and the second paragraph names the check that confirms it.
Comment on the issue, as tracker.md says: the cause, the loop command, and the missing seam when there is one. When the loop is a harness, put its text, redacted, in the comment, then delete the harness.
Completion: the branch has one commit over the trunk, or /build runs this skill, or the work is uncommitted as NO-SETUP.md says. The issue has the cause, or the report has it when the repo has no tracker.
Redact
Redact each secret in each command, output and artifact that you show: write <REDACTED> in its place. Print no value from an env file, because one pattern can also match a production line. To see which variables exist, list the names only: grep -oE '^[A-Z_]+=' <file>. Take the dev database name and user from the provision output. Build loops that read credentials from environment variables. Quote only the lines of a captured artifact that carry the signal. When the redacted output is not enough to find the cause, say so and ask the user.
Report
Issue · cause · commit, or the changed files when the work is uncommitted · missing seam, if any · each workaround and each issue filed for a fault outside the bug · each fallback from NO-SETUP.md · next step: /ship <n>, or the next step that NO-SETUP.md gives.
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.

