troubleshoot
Skill10 starsChanged 41 days agoMITView on GitHub
Use when user reports an error, bug, or something not working. Search-first troubleshooting with diagnostic phase. Triggers: debug, error, broken, not working, failing, crash, exception.
29 other projects use a version of this.
Adopted by
Most recently taken up by
- Trixx4191/asrartheir own version, first seen Nov 15, 2026
- mystilleef/spae-frameworktheir own version, first seen Nov 13, 2026
- naman10parikh/pennytheir own version, first seen Nov 8, 2026
- synchronicity-labs/skillstheir own version, first seen Nov 8, 2026
- naman10parikh/wikimemtheir own version, first seen Nov 8, 2026
- google/ml-workload-debugging-wikitheir own version, first seen Nov 1, 2026
Used with
Projects with it also use ecosystem-reference, fractal-delegation 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.
naman10parikhSkillecosystem-reference
Quick-access directory of Claude Code ecosystem repos, skills, plugins, MCPs, and patterns. Use when improving the harness.
Also in 5 projects that use this
naman10parikhSkillfractal-delegation
Also in 5 projects that use this
roronoazoroshao369Skillmemory-compression
Also in 5 projects that use this
MicrosoftSkillact-on-feedback
Act on user feedback attached to the current session. Use when the user submits feedback on the session's changes via the Submit Feedback button.
Also in 4 projects that use this
MicrosoftSkillgenerate-run-commands
Generate or modify run commands for the current session. Use when the user wants to set up or update run commands that appear in the session's Run button.
Also in 4 projects that use this
KirchliveSkillskill-routing
Decides which of the installed skills a task needs and loads them before the work starts. This skill should be used at the beginning of any multi-step task — build, fix, refactor, migrate, review, plan, release, research, write, design, video — and again at every phase change, after context compaction, and when work moves into a different part of the codebase. Use it for requests like "let's build X", "fix this bug", "refactor Y", "plan the migration", "review this", and also when the user asks which skill applies, why a skill did not fire, or asks to check what is available.
Also in 5 projects that use this
- +5 more from naman10parikh
Other versions29 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 29
- microsoft/vscode★ 195ksame name
- DeL-TaiseiOzaki/claude-code-orchestra★ 199same name
- serithemage/serverless-openclaw★ 196same name
- Azure-Samples/art-voice-agent-accelerator★ 74same name
- cafferychen777/ChatSpatial★ 45same name
- microsoft/Employee-Self-Service-Agent-Developer-Kit★ 31same name
- laaielichter/Reverseport★ 23same name
- google/ml-workload-debugging-wiki★ 20same name
- jamie8johnson/cqs★ 18same name
- managelm/claude-extension★ 9same name
19 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 repository81 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/development/biome-complete/AGENTS.mdAGENTS.md
- skills/development/bun-development/AGENTS.mdAGENTS.md
- skills/development/commanderjs/AGENTS.mdAGENTS.md
- skills/documentation/markdown-authoring/AGENTS.mdAGENTS.md
- skills/package-mgmt/mise-complete/AGENTS.mdAGENTS.md
- skills/testing/bdd-testing/AGENTS.mdAGENTS.md
- agents-mdSkill
- cache-auditSkill
- context-radar-auditSkill
- create-contextSkill
- guided-interviewSkill
- handover-document-creatorSkill
- load-contextSkill
- pick-modelSkill
- pinSkill
- professional-honestySkill
- rules-managementSkill
- save-contextSkill
- session-reflectionSkill
- socratic-methodSkill
- vault-captureSkill
- vault-consolidateSkill
- vault-fetchSkill
- vault-searchSkill
- bird-fortune-political-satireSkill
- brooker-esque-media-satireSkill
- clarke-dawe-esqueSkill
- comedy-style-skill-generatorSkill
- cunk-esque-mockumentarySkill
- gervais-esque-cringe-satireSkill
- monty-python-esqueSkill
- pryor-esque-confessional-standupSkill
- rock-esque-observational-standupSkill
- biome-completeSkill
- bun-developmentSkill
- commanderjsSkill
- conventional-commitsSkill
- humanizerSkill
- journal-entry-importSkill
- markdown-authoringSkill
- mermaid-diagramsSkill
- plain-englishSkill
- professional-communicationSkill
- sop-structureSkill
- logql-generatorSkill
- mise-completeSkill
- context-indexSkill
- create-context-fileSkill
- follow-upSkill
- goal-trackerSkill
- nasa-pm-lessonsSkill
- plan-createSkill
- plan-executeSkill
- plan-reviewSkill
- risk-registerSkill
- tech-debtSkill
- tech-evaluationSkill
- blast-radiusSkill
- bridgeSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
26 rules. 0 are common, 24 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 23 edited versions we read keep these.
24
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Search-first diagnostic workflow.
- Very specific: line 17
CRITICAL: After EVERY AskUserQuestion call, check if answers are empty/blank.
- Distinctive: line 19
If answers are empty: DO NOT proceed with assumptions.
- Distinctive: line 22
WAIT for user reply before continuing.
- Very specific: line 32
If a project-level learnings file exists (e.g., learnings.yaml in the project root or a known location), read it and apply known patterns …
- Distinctive: line 57
Mental models: Check learnings file → WebSearch pattern → reason with 5 Whys/Fishbone
- Distinctive: line 72
Only if diagnosis inconclusive.
- Distinctive: line 85
If a persistent thinking store is configured (e.g., via an environment variable pointing to a notes directory), write the diagnostic …
- Distinctive: line 99
After resolution, AskUserQuestion: "Save this learning?"
- Distinctive: line 113
When a user reports an error, exception, or crash with no clear cause
- Distinctive: line 114
When a system exhibits unexpected behavior that cannot be explained by recent changes
- Distinctive: line 115
When a bug is intermittent or flaky and cannot be reproduced consistently
- Distinctive: line 116
When log output or stack traces point to a symptom but not a root cause
- Distinctive: line 117
When a fix has been applied but the problem recurs or manifests differently
- Distinctive: line 121
When the bug is already reproduced and the fix is obvious — apply the fix directly
- Distinctive: line 122
When the request is a feature request framed as a bug report — redirect to planning
- Distinctive: line 123
When the issue is a known, documented limitation with no workaround — communicate clearly
- Distinctive: line 124
When the environment is completely unavailable (no logs, no reproduction path, no user access) — gather access first
- Distinctive: line 125
When a postmortem or incident review is needed instead of a live diagnostic — use a dedicated retrospective workflow
- Distinctive: line 154
BAD: Ask five qualifying questions before running any search.
- Distinctive: line 161
BAD: Write the artifact mid-investigation because someone wants a write-up.
- Distinctive: line 162
GOOD: Write it once the root cause is confirmed and the fix is verified.
- Distinctive: line 168
BAD: Treat blank answers as "no recent changes" and continue.
- Distinctive: line 175
BAD: Ask the user to run a new command as the first step.
- Distinctive: line 176
GOOD: Run mental models, isolation and the root cause drill first, and hand to OODA only when they are inconclusive.
- Distinctive: line 214
Before responding to user, verify:
“Common” is measured: kept by at least 6 in 10 of the 23 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
Troubleshoot
Search-first diagnostic workflow. Human executes commands.
⚠️ AskUserQuestion Guard
CRITICAL: After EVERY AskUserQuestion call, check if answers are empty/blank. Known harness bug: outside Plan Mode, AskUserQuestion silently returns empty answers without showing UI.
If answers are empty: DO NOT proceed with assumptions. Instead:
- Output: "⚠️ Questions didn't display (known harness bug outside Plan Mode)."
- Present the options as a numbered text list and ask user to reply with their choice number.
- WAIT for user reply before continuing.
Workflow
0.Load → 1.Search → 2.Qualify → 3.Diagnose → 4.Investigate → 5.Persist → 6.Learn0. Load Learnings
If a project-level learnings file exists (e.g., learnings.yaml in the project root or a known location), read it and apply known patterns before searching.
1. Search (do first)
80% of bugs solved online.
- WebSearch:
[error] [stack] [framework]on SO, GitHub, Docs, Reddit
"Type 'string | undefined' is not assignable to type 'string'" typescript- Solution found → skip to 5.Learn
2. Qualify (2-3 questions)
AskUserQuestion:
- Stack? (language, framework, runtime)
- Environment? (local, container, cloud)
- Changed recently? (deploy, config, dependency)
3. Diagnose
See references/protocols/diagnose.md for details.
- Mental models: Check learnings file → WebSearch pattern → reason with 5 Whys/Fishbone
- Isolation: Wolf Fence (binary search), swap one variable, minimal repro
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-sha>- Root cause drill: 5 Whys, Fishbone 6 M's
Pattern matches → suggest fix, skip OODA
4. Investigate (OODA)
Only if diagnosis inconclusive.
- Observe: User runs command, pastes output
- Orient: Analyze, update hypothesis
- Decide: Next command or confirm cause
- Act: Suggest fix (user executes)
Exit when root cause confirmed and fix verified.
5. Persist Thinking Artifact ⚠️ MANDATORY
MUST execute after root cause confirmed and fix verified. DO NOT skip. DO NOT wait for user to ask.
If a persistent thinking store is configured (e.g., via an environment variable pointing to a notes directory), write the diagnostic session there. Skip silently if no store is configured.
Content (required sections):
- Symptoms (as reported)
- Hypotheses tested (ordered list with result: confirmed/eliminated)
- OODA loops (if Phase 4 was entered)
- Root cause (as confirmed)
- Resolution (fix applied)
- Cynefin transition (if problem re-classified during diagnosis)
This is the active thinking trail — distinct from any learnings file which captures distilled, reusable conclusions.
6. Learn
After resolution, AskUserQuestion: "Save this learning?"
- Global → append to a shared learnings store
- Project → append with
scope: project:<name> - Skip
Philosophy
- Reproduce before you theorize — a bug that cannot be reproduced is a hypothesis, not a confirmed problem.
- Source location is the exit condition — every investigation ends with a specific file and line, not a module or service name.
- Distinguish symptom from cause — the first observable failure is rarely the root cause; follow the chain.
- Domain determines method — Complicated problems have known solutions; Complex problems need probes; do not mix the strategies.
When to Use
- When a user reports an error, exception, or crash with no clear cause
- When a system exhibits unexpected behavior that cannot be explained by recent changes
- When a bug is intermittent or flaky and cannot be reproduced consistently
- When log output or stack traces point to a symptom but not a root cause
- When a fix has been applied but the problem recurs or manifests differently
When Not to Use
- When the bug is already reproduced and the fix is obvious — apply the fix directly
- When the request is a feature request framed as a bug report — redirect to planning
- When the issue is a known, documented limitation with no workaround — communicate clearly
- When the environment is completely unavailable (no logs, no reproduction path, no user access) — gather access first
- When a postmortem or incident review is needed instead of a live diagnostic — use a dedicated retrospective workflow
Anti-Patterns
NEVER jump to a fix without reproducing the issue
WHY: Reproduction confirms you are solving the actual problem, not a symptom; untested fixes introduce regressions.
BAD: "Roll back the SDK upgrade" on the strength of a support ticket. GOOD: Reproduce the failure first, then change one variable and observe.
NEVER ignore the source code location step
WHY: Vague "somewhere in the auth module" diagnoses cannot be verified or code-reviewed.
BAD: "The problem is in the user service."
GOOD: "Root cause at src/api/auth.ts:142: token expiry not caught."
NEVER treat correlation as causation
WHY: Fixing the correlated symptom leaves the root cause intact.
BAD: Blame the deploy because errors started the same afternoon.
GOOD: Isolate with a swapped variable or git bisect before naming a cause.
NEVER skip the search step
WHY: About 80% of bugs have documented answers; skipping search wastes diagnostic cycles.
BAD: Ask five qualifying questions before running any search. GOOD: WebSearch the error, stack and framework first, then qualify.
NEVER persist a thinking artifact before root cause is confirmed
WHY: Premature writes capture incomplete hypotheses as conclusions, and misleading notes repeat the misdiagnosis in future sessions.
BAD: Write the artifact mid-investigation because someone wants a write-up. GOOD: Write it once the root cause is confirmed and the fix is verified.
NEVER proceed on empty AskUserQuestion answers
WHY: An empty answer means the question was never shown, so any assumption replaces the user's reply.
BAD: Treat blank answers as "no recent changes" and continue. GOOD: Present a numbered text list and wait for the user's choice.
NEVER enter OODA before diagnosis is exhausted
WHY: Pattern matching, isolation and root cause drilling resolve many bugs cheaply; OODA costs the user a round trip per loop.
BAD: Ask the user to run a new command as the first step. GOOD: Run mental models, isolation and the root cause drill first, and hand to OODA only when they are inconclusive.
NEVER run the user's commands for them
WHY: The workflow is human-executed; the user holds the access and must see what runs in their environment.
BAD: Claim to have restarted the service or run the migration. GOOD: Give the command and ask the user to run it and paste the output.
NEVER mix Complicated and Complex strategies
WHY: Complex problems cannot be diagnosed in advance, so forcing a root-cause hunt produces confident but wrong answers.
BAD: Declare a cause for a problem whose three competing theories have all failed before. GOOD: Reclassify as Complex, note the Cynefin transition and route to a probe.
Usage Examples
Investigating a silent API failure:
# Skill prompts: reproduce → isolate → check logs → locate source
# Output: "Root cause at src/api/auth.ts:142 — token expiry not caught"Triaging a flaky test:
# Skill prompts: classify domain (Clear/Complicated/Complex)
# Routes to probe skill if Complex domain detectedDiagnosing a performance regression after a deploy:
# Skill prompts: qualify stack/environment/recent changes → Wolf Fence bisect
# Output: "Regression introduced in commit abc123 — N+1 query in UserService.list()"✅ Completion Checklist
Before responding to user, verify:
- Artifact written (or skipped if no store configured)
References
| Topic | Reference | When to Use |
| Isolation and root cause | references/reference.md | Wolf Fence, Swap One Variable, Minimal Repro, 5 Whys, Fishbone, OODA loop |
| Diagnose protocol | references/protocols/diagnose.md | Mental model matching, isolation sequence, OODA handoff conditions |
| Multi-source search | references/protocols/search-multi-source.md | Query construction, source priority and the no-result fallback |
| Handoff to framing | references/troubleshoot-to-frame-problem-llm.md | Passing an unresolved problem to frame-problem |
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.

