agentleFS
Sign inStart free
GrishaAngelovGHGrishaAngelovGH/gemini-cli-agent-skills/bug-investigator/SKILL.md

bug-investigator

Skill16 starsChanged 10 months agoMITView on GitHub

Expert guidance for systematic bug hunting, root-cause analysis, and regression testing. Use this skill when the user reports a bug, unexpected behavior, or when you need to troubleshoot complex issues in the codebase.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. MageByte-Zero/spec-superflow★ 875same name

    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 repository6 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Trace the Data: Follow the flow of data leading up to the failure.

    line 13
  2. Distinctive:

    Automate the Failure: Write a failing unit or integration test that demonstrates the bug.

    line 18
  3. Distinctive:

    React: Use React Testing Library to simulate user interactions.

    line 20
  4. Distinctive:

    Java: Use JUnit/Mockito for unit tests.

    line 21
  5. Very specific:

    Python: Use pytest or unittest.

    line 22
  6. Very specific:

    Node.js: Use jest or mocha.

    line 23
  7. Very specific:

    Consult the Checklist: Read references/checklist.md to quickly rule out common pitfalls like race conditions, memory leaks, or …

    line 26
  8. Distinctive:

    The "5 Whys": Ask why the failure occurred, then why that happened, until you reach the fundamental flaw.

    line 27
  9. Distinctive:

    Check Boundary Conditions: Look for nulls, empty arrays, off-by-one errors, or unexpected types.

    line 28
  10. Distinctive:

    Review Recent Changes: Use git log or check recent modifications in the affected files to see if a recent change introduced the regression.

    line 30
  11. Distinctive:

    Verify the Fix: Run the reproduction test created in Step 2.

    line 34
  12. Distinctive:

    Check for Regressions: Run the full test suite (or at least all tests in the affected module) to ensure no other functionality was broken.

    line 35
  13. Distinctive:

    Refactor (Optional): If the fix revealed a deeper architectural flaw, consider a clean refactor now that you have tests protecting the …

    line 36
  14. Distinctive:

    Add Guardrails: Add assertions, type checks, or improved logging to catch similar issues earlier in the future.

    line 39
  15. Distinctive:

    Document the "Why": Add a brief comment if the fix addresses a non-obvious edge case or a subtle library quirk.

    line 40

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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.

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

Bug Investigation & Resolution Protocol

You are now operating as an Expert Bug Investigator. Your goal is to move from a vague symptom to a verified fix using a rigorous, scientific approach.

1. Symptom Analysis & Information Gathering

  • Identify the "What": What is the observed behavior? What is the expected behavior?
  • Identify the "Where": Which components, services, or files are involved?
  • Trace the Data: Follow the flow of data leading up to the failure. Use grep or search_file_content to find where relevant variables or error messages are defined.

2. Reproduction (The Golden Rule)

  • NEVER attempt a fix without a reproduction case.
  • Create a Minimal Reproduction: Try to isolate the bug in a small, standalone script or a new test case.
  • Automate the Failure: Write a failing unit or integration test that demonstrates the bug. This ensures the bug is real and provides a way to verify the fix later.
  • Technology-Specific Testing:
    • React: Use React Testing Library to simulate user interactions.
    • Java: Use JUnit/Mockito for unit tests.
    • Python: Use pytest or unittest.
    • Node.js: Use jest or mocha.

3. Root Cause Analysis (RCA)

  • Consult the Checklist: Read references/checklist.md to quickly rule out common pitfalls like race conditions, memory leaks, or configuration errors.
  • The "5 Whys": Ask why the failure occurred, then why that happened, until you reach the fundamental flaw.
  • Check Boundary Conditions: Look for nulls, empty arrays, off-by-one errors, or unexpected types.
  • State Analysis: Examine the state of the application at the moment of failure. Use logging or debug statements if necessary.
  • Review Recent Changes: Use git log or check recent modifications in the affected files to see if a recent change introduced the regression.

4. Implementation & Verification

  • Apply the Fix: Make the most targeted, minimal change necessary to resolve the root cause.
  • Verify the Fix: Run the reproduction test created in Step 2. It should now pass.
  • Check for Regressions: Run the full test suite (or at least all tests in the affected module) to ensure no other functionality was broken.
  • Refactor (Optional): If the fix revealed a deeper architectural flaw, consider a clean refactor now that you have tests protecting the logic.

5. Prevention

  • Add Guardrails: Add assertions, type checks, or improved logging to catch similar issues earlier in the future.
  • Document the "Why": Add a brief comment if the fix addresses a non-obvious edge case or a subtle library quirk.

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.

Check your setup, free