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
- filipe-campos/walphtheir own version, first seen Nov 15, 2026
- Vinix24/vnx-orchestrationtheir own version, first seen Nov 12, 2026
- BrightGold70/skillstheir own version, first seen Nov 8, 2026
- d-o-hub/github-template-ai-agentstheir own version, first seen Nov 3, 2026
- claude-world/director-mode-litetheir own version, first seen Nov 1, 2026
- xfstudio/skillstheir own version, first seen Oct 13, 2026
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.
belokonmSkillsecurity-engineer
Expert in infrastructure security, DevSecOps pipelines, and zero-trust architecture design.
Also in 4 projects that use this
am-willSkillplanner
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
VercelSkilltechnical-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
leonardomsoSkilltest-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
GitHubSkilldocumentation-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
AnthropicSkillsystem-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
Other versions34 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 34
- toonight/get-shit-done-for-antigravity★ 952same name
- TheDecipherist/claude-code-mastery-project-starter-kit★ 337same name
- Othmane-Khadri/YALC-the-GTM-operating-system★ 298same name
- antonbabenko/deliberation★ 183same name
- wado-lang/wado★ 120same name
- claude-world/director-mode-lite★ 80same name
- Vinix24/vnx-orchestration★ 63same name
- jshsakura/awesome-opencode-skills★ 31same name
- belokonm/claude-supercode-skills★ 11same name
- botlearn-ai/botlearn-skills★ 9same name
24 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.
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- accessibility-auditorSkill
- architectSkill
- auditorSkill
- awsSkill
- bug-fix-teammateSkill
- builderSkill
- cleanup-specialistSkill
- code-reviewSkill
- commit-messagesSkill
- concept-explainerSkill
- context-economySkill
- cross-provider-translationSkill
- datadogSkill
- debugging-and-error-recoverySkill
- debugging-tutorSkill
- dockerSkill
- doormanSkill
- elasticsearchSkill
- emailSkill
- envoySkill
- githubSkill
- gitlabSkill
- goal-refinementSkill
- heraldSkill
- implementation-plannerSkill
- inspectorSkill
- institutional-knowledgeSkill
- issue-managerSkill
- jiraSkill
- kubernetesSkill
- librarianSkill
- linearSkill
- mailmanSkill
- mediatorSkill
- mongodbSkill
- mysqlSkill
- onboarding-planSkill
- operatorSkill
- oracleSkill
- postgresSkill
- pull-request-assistantSkill
- redisSkill
- release-notesSkill
- rememberSkill
- reviewerSkill
- runtime-healthSkill
- scribeSkill
- security-and-hardeningSkill
- sentinelSkill
- sentrySkill
- society-integritySkill
- spec-driven-developmentSkill
- stewardSkill
- strategistSkill
- telegramSkill
- test-driven-developmentSkill
- testerSkill
- validation-and-enforcementSkill
- wardenSkill
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
- Distinctive: line 16
When any error, exception, or unexpected behavior occurs
- Distinctive: line 17
When a test is failing and the cause is unclear
- Distinctive: line 18
When a CI pipeline fails
- Distinctive: line 19
When behavior changed after a seemingly unrelated change
- Distinctive: line 20
When a bug was reported but cannot yet be reproduced
- Distinctive: line 28
Read the full stack trace.
- Distinctive: line 29
Not the first line. All of it.
- Distinctive: line 35
When did this start happening?
- Distinctive: line 44
If it cannot be reproduced, the investigation continues — it is not closed
- Distinctive: line 55
Do not test all hypotheses simultaneously — you won't know which one was right.
- Distinctive: line 60
Add a targeted log statement at the suspected location
- Distinctive: line 61
Write a unit test that isolates the suspected behavior
- Distinctive: line 62
Add a breakpoint and inspect the actual state at that line
- Very specific: line 68
Never add try/catch to silence the error as a hypothesis test.
- Distinctive: line 83
After every bug fix, in this order:
- Distinctive: line 84
Write a regression test that would have caught this bug before the fix was applied — it must fail on the unfixed code
- Distinctive: line 86
Commit the regression test and fix as separate commits:
- Distinctive: line 89
Document the root cause in the PR description
- Distinctive: line 94
Read the full build log — not just the summary
- Distinctive: line 112
No regression test accompanying the fix
“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.
Files
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.
- Identify the minimal reproduction case
- Confirm the error occurs consistently with that input
- Confirm the error does not occur without that input
- 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:
- Add a targeted log statement at the suspected location
- Write a unit test that isolates the suspected behavior
- 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
nullat 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:
- Write a regression test that would have caught this bug before the fix was applied — it must fail on the unfixed code
- Apply the fix — the test must now pass
- Commit the regression test and fix as separate commits:
test(scope): add regression test for [bug description]fix(scope): [fix description]
- Document the root cause in the PR description
CI Failure Diagnosis
When a CI pipeline fails:
- Read the full build log — not just the summary
- Find the first failure — subsequent failures are often cascading effects
- Reproduce locally using the same command CI ran
- 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.jsonvsnode_modules - Lint/type error → fix the code, not the lint config
Red Flags
- Adding
try/catchto hide an error without finding its cause - Using
|| nullor?? undefinedwithout 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 think | What 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
releasetag withgit logfor that tag before forming the hypothesis - Step 5 — systemic issues escalate via
begin_seer_issue_fixper the criteria indocs/portals/sentry.md; targeted fixes stay in-protocol
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
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.

