agentleFS
Sign inStart free
rafaelobrafaelob/pragmatic-agent-skills/skills/diagnosing-bugs/SKILL.md

diagnosing-bugs

Skill23 starsChanged 8 days agoApache-2.0View on GitHub

Use to reproduce a bug from evidence, or a failing test whose code may be wrong, and isolate one cause before changing code. Not proving a seam is wired -> layered-testing-executor.

We split this skill into the rules it gives an agent

1 rule. 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 177 edited versions we read keep these.

  • 0

    Distinctive

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

    When the cause is already established and the fix needs its failing test first, use tdd.

    line 58

“Common” is measured: kept by at least 6 in 10 of the 177 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 by discriminating evidence

Read the actual error, reported scenario and affected revision/configuration. Inspect relevant logs without exposing secrets or personal data. Reduce the symptom to a small repeatable check on the boundary that can reproduce it. A health check or import failure is not a reproduction of a wrong business result.

Form a hypothesis with a predicted observation. Choose the next inspection or experiment that distinguishes plausible causes; do not change several unrelated things or rerun the same failing command without changing the hypothesis. Use a controlled schedule for a suspected race and representative measurement for a performance defect, rather than arbitrary sleeps or speculative optimization.

Useful regression

When the defect is reproducible, strengthen the existing behavioral test that should have caught it and verify that it fails for the defect and passes after correction. Add a new test only when no existing test can be made sensitive to it: a regression test without a genuine gap in behavior coverage is noise. Avoid duplicating the same assertion across unit, service and browser layers unless each exposes a distinct failure boundary. Read references/LOOP_TAXONOMY.md when choosing or constructing the reproduction's pass/fail signal; its last-resort loop is scripts/hitl_loop_template.py (copy it, edit run(), the human follows the terminal prompts).

If reproduction is unavailable, continue useful permitted static investigation and report the limit. Static reasoning can demonstrate some defects, but it does not demonstrate runtime recovery. Do not manufacture a failing test unrelated to the symptom or claim a runtime fix from a plausible patch alone.

After the correction, check the original scenario and directly related risk, then run applicable project gates. Search for siblings only when the same causal mechanism plausibly applies. Remove owned temporary instrumentation; retain the regression and a brief explanation in the current work item. Do not turn every bug into a whole-repository audit.

When the cause is already established and the fix needs its failing test first, use tdd; for a Windows-only path, quoting or encoding failure, use windows-shell-interop.

Download now (ZIP)

  • Other versions192 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 192

    1. mattpocock/skills★ 309ksame name
    2. QuivrHQ/quivr★ 40ksame name
    3. GreyDGL/PentestGPT★ 16ksame name
    4. ArcReel/ArcReel★ 6ksame name
    5. vinvcn/mattpocock-skills-zh-CN★ 5.5ksame name
    6. withcoral/coral★ 4.9ksame name
    7. bestofjs/bestofjs★ 3.1ksame name
    8. getsentry/sentry-react-native★ 1.8ksame name
    9. epam/ketcher★ 927same name
    10. getsentry/sentry-dart★ 877same name

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

  • Used alongsideProjects with it also use setup-ts-deep-modules, loop-me 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.
    • liufeng1976Skill

      setup-ts-deep-modules

      Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.

      Also in 38 projects that use this

    • RoentekSkill

      loop-me

      Grill me about specs for the workflows I want to build, within this workspace.

      Also in 50 projects that use this

    • LesaniSkill

      writing-beats

      Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.

      Also in 53 projects that use this

    • AWSSkill

      to-questionnaire

      Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

      Also in 80 projects that use this

    • AWSSkill

      wizard

      Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.

      Also in 115 projects that use this

    • ryotaroh180105Skill

      claude-handoff

      Hand the current conversation off to a fresh background agent that picks up the work immediately.

      Also in 37 projects that use this

    • +2 more from aws
  • In this repository21 other files it gives its agents.

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.

Check your setup, free