agentleFS
SantiagoVqzSantiagoVqz/claude-skills/skills/2-build/diagnose/SKILL.md

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

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.
  • victorgarciaesgiSkill

    zoom-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

  • GoogleSkill

    to-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

  • GoogleSkill

    to-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

  • simo97Skill

    write-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

  • simo97Skill

    edit-article

    The user will invoke this skill to help them edit an article.

    Also in 17 projects that use this

  • kennethkeimSkill

    ubiquitous-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

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
  1. Very specific:

    When /build runs this skill, skip the steps marked "(not under /build)".

    line 17
  2. Distinctive:

    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.

    line 19
  3. Very specific:

    Read the ## Agent skills block in AGENTS.md, then docs/agents/tracker.md.

    line 25
  4. Very specific:

    Call the Skill tool with worktree for fix/<n>-<slug>, made from the trunk.

    line 33
  5. Distinctive:

    When you cannot build a loop, stop.

    line 58
  6. Distinctive:

    When the loop needs production facts, ask for all of them in one message.

    line 60
  7. Distinctive:

    Before this command exists, read only the code that the loop calls.

    line 69
  8. Very specific:

    Run the loop, and see it go red.

    line 73
  9. Distinctive:

    Write 3 to 5 hypotheses, ranked.

    line 81
  10. Very specific:

    Test one prediction at a time.

    line 89
  11. Distinctive:

    When the user's pick is false, go to the next hypothesis in the ranking.

    line 93
  12. Distinctive:

    When no offline loop can test the cause, the cause is not confirmed.

    line 95
  13. Distinctive:

    Run it, and see it fail on the symptom.

    line 106
  14. Distinctive:

    Run the test, and see it pass.

    line 108
  15. Distinctive:

    Run the loop from step 3 on the original scenario.

    line 109
  16. Distinctive:

    Search for the debug prefix with git grep.

    line 117
  17. Distinctive:

    Run the loop from step 3 one more time.

    line 118
  18. Distinctive:

    Delete each harness and script that the regression test replaces.

    line 119
  19. Very specific:

    Run the typecheck, the lint, and the tests that the fix adds or touches.

    line 125
  20. Distinctive:

    Write the card in your message, before the question.

    line 131
  21. Very specific:

    Keep "Check yourself" to three steps or fewer.

    line 143

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. A failing test at the seam that reaches the bug.
  2. A curl script against a running dev server.
  3. A CLI call with a fixture input, compared with a known-good output.
  4. A headless browser script that drives the UI and checks the DOM, the console or the network.
  5. A replay of a captured request, payload or event log through the code path.
  6. A throwaway harness: the smallest part of the system that runs the code path in one call.
  7. A fuzz loop: many random inputs, for output that is sometimes wrong.
  8. A bisect harness: git bisect run between a good and a bad commit.
  9. A differential loop: one input through the old and the new version, with the outputs compared.
  10. A human loop. Call the Skill tool with ui-check to 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:

  1. Turn the minimised repro into a failing test at the seam.
  2. Run it, and see it fail on the symptom. When you forced the red with a change to the code, confirm with git diff that the change is there, and undo it after.
  3. Fix the cause.
  4. Run the test, and see it pass.
  5. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.