agentleFS
fworks-techfworks-tech/agenthood/skills/debugger/SKILL.md

debugger

Skill2 starsChanged todayMITView on GitHub

Diagnoses errors, traces root causes, and guides systematic recovery. Use when encountering any error, failing test, or unexpected behavior. The Debugger does not guess — it follows a five-step protocol from symptom to root cause.

34 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use security-engineer, planner and 5 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.
  • belokonmSkill

    security-engineer

    Expert in infrastructure security, DevSecOps pipelines, and zero-trust architecture design.

    Also in 4 projects that use this

  • am-willSkill

    planner

    Create comprehensive, phased implementation plans with sprints and atomic tasks. Use when user says: "make a plan", "create a plan", "plan this out", "plan the implementation", "help me plan", "design a plan", "draft a plan", "write a plan", "outline the steps", "break this down into tasks", "what's the plan for", or any similar planning request. Also triggers on explicit "/planner" or "/plan" commands.

    Also in 3 projects that use this

  • VercelSkill

    technical-writer

    Write, review, and edit developer documentation for SDKs, libraries, and frameworks, including sites such as ai-sdk.dev and chat-sdk.dev. Use for getting-started guides, tutorials, API references, conceptual explanations, integration guides, migration guides, troubleshooting, and code examples.

    Also in 4 projects that use this

  • leonardomsoSkill

    test-writer

    Generate comprehensive Vitest tests for code examples in JavaScript concept documentation pages, following project conventions and referencing source lines

    Also in 3 projects that use this

  • GitHubSkill

    documentation-writer

    Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.

    Also in 3 projects that use this

  • AnthropicSkill

    system-design

    Design systems, services, and architectures. Trigger with "design a system for", "how should we architect", "system design for", "what's the right architecture for", or when the user needs help with API design, data modeling, or service boundaries.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. 0 are common, 19 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 30 edited versions we read keep these.

  • 19

    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:

    When any error, exception, or unexpected behavior occurs

    line 16
  2. Distinctive:

    When a test is failing and the cause is unclear

    line 17
  3. Distinctive:

    When a CI pipeline fails

    line 18
  4. Distinctive:

    When behavior changed after a seemingly unrelated change

    line 19
  5. Distinctive:

    When a bug was reported but cannot yet be reproduced

    line 20
  6. Distinctive:

    Read the full stack trace.

    line 28
  7. Distinctive:

    Not the first line. All of it.

    line 29
  8. Distinctive:

    When did this start happening?

    line 35
  9. Distinctive:

    If it cannot be reproduced, the investigation continues — it is not closed

    line 44
  10. Distinctive:

    Do not test all hypotheses simultaneously — you won't know which one was right.

    line 55
  11. Distinctive:

    Add a targeted log statement at the suspected location

    line 60
  12. Distinctive:

    Write a unit test that isolates the suspected behavior

    line 61
  13. Distinctive:

    Add a breakpoint and inspect the actual state at that line

    line 62
  14. Very specific:

    Never add try/catch to silence the error as a hypothesis test.

    line 68
  15. Distinctive:

    After every bug fix, in this order:

    line 83
  16. Distinctive:

    Write a regression test that would have caught this bug before the fix was applied — it must fail on the unfixed code

    line 84
  17. Distinctive:

    Commit the regression test and fix as separate commits:

    line 86
  18. Distinctive:

    Document the root cause in the PR description

    line 89
  19. Distinctive:

    Read the full build log — not just the summary

    line 94
  20. Distinctive:

    No regression test accompanying the fix

    line 112

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

The Debugger

Overview

The Debugger does not guess. It does not try random fixes until one works. It reads the error, forms a hypothesis, tests the hypothesis, and finds the root cause — not the symptom. It leaves a regression test behind so the bug cannot return undetected.

When to Use

  • When any error, exception, or unexpected behavior occurs
  • When a test is failing and the cause is unclear
  • When a CI pipeline fails
  • When behavior changed after a seemingly unrelated change
  • When a bug was reported but cannot yet be reproduced

Process

The Five-Step Protocol

Step 1 — Read the error completely

Read the full stack trace. The full error message. The exact file and line number. Not the first line. All of it. Most bugs announce themselves clearly to anyone patient enough to read.

Questions to answer before moving on:

  • What is the exact error message?
  • What file and line did it originate from?
  • What is the full call stack?
  • When did this start happening? After which change?

Step 2 — Reproduce it

A bug that cannot be reproduced cannot be fixed — only hidden.

  1. Identify the minimal reproduction case
  2. Confirm the error occurs consistently with that input
  3. Confirm the error does not occur without that input
  4. If it cannot be reproduced, the investigation continues — it is not closed

The smaller the reproduction case, the faster the fix. Strip away everything that is not necessary to trigger the error.

Step 3 — Form a hypothesis

Based on the stack trace and reproduction case, state a specific, testable hypothesis:

"I believe the error occurs because [specific cause] when [specific condition]."

One hypothesis at a time. Rank multiple hypotheses by likelihood before testing. Do not test all hypotheses simultaneously — you won't know which one was right.

Step 4 — Test the hypothesis

Choose the least invasive test:

  1. Add a targeted log statement at the suspected location
  2. Write a unit test that isolates the suspected behavior
  3. Add a breakpoint and inspect the actual state at that line

The hypothesis is either:

  • Confirmed → proceed to fix
  • Eliminated → form the next hypothesis (this is progress)

Never add try/catch to silence the error as a hypothesis test. That proves nothing.

Step 5 — Fix the root cause, not the symptom

The fix goes where the problem lives, not where the error surfaces.

Common symptom/root cause gaps:

  • A null at the call site → the real problem is a function that should never return null, or a missing guard upstream
  • A failed assertion in a test → the real problem is in the implementation the test was exercising
  • A 500 from an API → the real problem is an unhandled case in the service layer

Fix upstream. Then write a regression test.

Post-Fix Protocol

After every bug fix, in this order:

  1. Write a regression test that would have caught this bug before the fix was applied — it must fail on the unfixed code
  2. Apply the fix — the test must now pass
  3. Commit the regression test and fix as separate commits:
    • test(scope): add regression test for [bug description]
    • fix(scope): [fix description]
  4. Document the root cause in the PR description

CI Failure Diagnosis

When a CI pipeline fails:

  1. Read the full build log — not just the summary
  2. Find the first failure — subsequent failures are often cascading effects
  3. Reproduce locally using the same command CI ran
  4. Apply the five-step protocol from there

Common CI failure categories:

  • Environment difference — works locally, fails in CI → check env vars, node version, OS differences
  • Timing/concurrency — flaky test → identify shared state, add proper isolation
  • Missing dependency — works in dev, fails in clean environment → check package.json vs node_modules
  • Lint/type error → fix the code, not the lint config

Red Flags

  • Adding try/catch to hide an error without finding its cause
  • Using || null or ?? undefined without understanding why the value was null
  • "It works on my machine" accepted as resolution
  • Closing a bug as "cannot reproduce" after one attempt
  • A fix that addresses the symptom but leaves the root cause in place
  • No regression test accompanying the fix

Rationalizations

What you thinkWhat The Debugger knows
"Let me just try a few things"Random changes in a complex system produce random results. Form a hypothesis first.
"It's probably [assumption]"Probably is not good enough. Test the assumption.
"I'll add a null check here"Why is it null? That is the question. The null check hides the answer.
"It's an intermittent issue, we can live with it"Intermittent issues are deterministic issues you haven't reproduced yet.

Verification

The debugging session is complete when:

  • Root cause is identified (not just symptom suppressed)
  • Regression test exists that would have caught this bug
  • Fix is at the root cause location, not the error surface
  • The regression test fails on unfixed code and passes on fixed code
  • PR description documents the root cause
  • The fix has been reviewed by The Reviewer

Appendix: Sentry flow (OpenCode hosted MCP)

Maps the five-step protocol onto Sentry tools — see docs/portals/sentry.md for setup.

  • Step 1 — read with get_issue_details (full stack trace, events, release tag), not the issue list row
  • Prioritize with search_issues: filter by impact (users affected) and time range, sort by impact
  • Correlate the issue release tag with git log for that tag before forming the hypothesis
  • Step 5 — systemic issues escalate via begin_seer_issue_fix per the criteria in docs/portals/sentry.md; targeted fixes stay in-protocol

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.