agentleFS
Sign inStart free
jMertajMerta/codex-skills/bug-triage/SKILL.md

bug-triage

Skill130 starsChanged 11 months agoMITView on GitHub

Use when the user reports a bug, regression, runtime error, failing build, or broken test and wants reproduction, diagnosis, root-cause analysis, or an authorized fix. Isolates the shared cause and verifies the smallest relevant change.

We split this skill into the rules it gives an agent

8 rules. 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 27 edited versions we read keep these.

  • 7

    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. Distinctive:

    Read repository instructions and inspect the current branch, status, and relevant diff.

    line 10
  2. Distinctive:

    Use the smallest reliable reproduction.

    line 17
  3. Distinctive:

    If the failure is intermittent, control time, randomness, concurrency, data, and retries one variable at a time.

    line 18
  4. Distinctive:

    Use history or git bisect only when a regression boundary will materially shorten the search.

    line 21
  5. Distinctive:

    Add or adapt the smallest regression check that fails for the confirmed cause.

    line 32
  6. Distinctive:

    Avoid unrelated refactors, dependency upgrades, formatting churn, and broad exception handling.

    line 34
  7. Distinctive:

    Use the package manager, wrapper, and commands already selected by the repository.

    line 37
  8. Very specific:

    Use references/bug-report-template.md only when the user needs a reusable intake form.

    line 49

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

Bug triage

Establish scope

  1. Read repository instructions and inspect the current branch, status, and relevant diff.
  2. Determine whether the user asked only for diagnosis or also authorized a fix.
  3. Inspect available errors, logs, tests, and code before asking for missing details.
  4. Record expected behavior, actual behavior, environment, frequency, and last known good state when they affect the investigation.

Reproduce and isolate

  1. Use the smallest reliable reproduction. Preserve the original failure output.
  2. If the failure is intermittent, control time, randomness, concurrency, data, and retries one variable at a time.
  3. Trace the failing path end to end. Search every caller of the function or component before editing it.
  4. Form a falsifiable hypothesis and run the narrowest check that can confirm or reject it.
  5. Use history or git bisect only when a regression boundary will materially shorten the search.

Separate these outcomes explicitly:

  • confirmed product regression;
  • pre-existing or baseline failure;
  • environment, credentials, service, or dependency failure;
  • insufficient evidence to reproduce.

Fix when authorized

  1. Add or adapt the smallest regression check that fails for the confirmed cause.
  2. Fix the shared root cause rather than guarding one visible caller.
  3. Avoid unrelated refactors, dependency upgrades, formatting churn, and broad exception handling.
  4. Re-run the reproduction, focused regression check, and the smallest relevant project checks.

Use the package manager, wrapper, and commands already selected by the repository. Infer them from repository instructions, manifests, lockfiles, and scripts; do not substitute another tool just because it is installed locally.

Report

Include:

  • Observed: exact symptom and affected scope.
  • Root cause: confirmed explanation, or the leading hypothesis clearly labeled.
  • Change: files and behavior changed, or diagnosis only.
  • Verification: commands and results, including baseline failures.
  • Remaining risk: untested paths, flaky behavior, or external blockers.

Use references/bug-report-template.md only when the user needs a reusable intake form.

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.

Reviews can't be read right now.

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