agentleFS
pantheon-orgpantheon-org/tekhne/skills/software-engineering/troubleshoot/SKILL.md

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

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.
  • naman10parikhSkill

    ecosystem-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

  • naman10parikhSkill

    fractal-delegation

    Also in 5 projects that use this

  • roronoazoroshao369Skill

    memory-compression

    Also in 5 projects that use this

  • MicrosoftSkill

    act-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

  • MicrosoftSkill

    generate-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

  • KirchliveSkill

    skill-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

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

    Search-first diagnostic workflow.

    line 13
  2. Very specific:

    CRITICAL: After EVERY AskUserQuestion call, check if answers are empty/blank.

    line 17
  3. Distinctive:

    If answers are empty: DO NOT proceed with assumptions.

    line 19
  4. Distinctive:

    WAIT for user reply before continuing.

    line 22
  5. Very specific:

    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 …

    line 32
  6. Distinctive:

    Mental models: Check learnings file → WebSearch pattern → reason with 5 Whys/Fishbone

    line 57
  7. Distinctive:

    Only if diagnosis inconclusive.

    line 72
  8. Distinctive:

    If a persistent thinking store is configured (e.g., via an environment variable pointing to a notes directory), write the diagnostic …

    line 85
  9. Distinctive:

    After resolution, AskUserQuestion: "Save this learning?"

    line 99
  10. Distinctive:

    When a user reports an error, exception, or crash with no clear cause

    line 113
  11. Distinctive:

    When a system exhibits unexpected behavior that cannot be explained by recent changes

    line 114
  12. Distinctive:

    When a bug is intermittent or flaky and cannot be reproduced consistently

    line 115
  13. Distinctive:

    When log output or stack traces point to a symptom but not a root cause

    line 116
  14. Distinctive:

    When a fix has been applied but the problem recurs or manifests differently

    line 117
  15. Distinctive:

    When the bug is already reproduced and the fix is obvious — apply the fix directly

    line 121
  16. Distinctive:

    When the request is a feature request framed as a bug report — redirect to planning

    line 122
  17. Distinctive:

    When the issue is a known, documented limitation with no workaround — communicate clearly

    line 123
  18. Distinctive:

    When the environment is completely unavailable (no logs, no reproduction path, no user access) — gather access first

    line 124
  19. Distinctive:

    When a postmortem or incident review is needed instead of a live diagnostic — use a dedicated retrospective workflow

    line 125
  20. Distinctive:

    BAD: Ask five qualifying questions before running any search.

    line 154
  21. Distinctive:

    BAD: Write the artifact mid-investigation because someone wants a write-up.

    line 161
  22. Distinctive:

    GOOD: Write it once the root cause is confirmed and the fix is verified.

    line 162
  23. Distinctive:

    BAD: Treat blank answers as "no recent changes" and continue.

    line 168
  24. Distinctive:

    BAD: Ask the user to run a new command as the first step.

    line 175
  25. Distinctive:

    GOOD: Run mental models, isolation and the root cause drill first, and hand to OODA only when they are inconclusive.

    line 176
  26. Distinctive:

    Before responding to user, verify:

    line 214

“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.

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

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:

  1. Output: "⚠️ Questions didn't display (known harness bug outside Plan Mode)."
  2. Present the options as a numbered text list and ask user to reply with their choice number.
  3. WAIT for user reply before continuing.

Workflow

0.Load → 1.Search → 2.Qualify → 3.Diagnose → 4.Investigate → 5.Persist → 6.Learn

0. 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.

  1. Mental models: Check learnings file → WebSearch pattern → reason with 5 Whys/Fishbone
  2. Isolation: Wolf Fence (binary search), swap one variable, minimal repro
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-sha>
  1. 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 detected

Diagnosing 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

TopicReferenceWhen to Use
Isolation and root causereferences/reference.mdWolf Fence, Swap One Variable, Minimal Repro, 5 Whys, Fishbone, OODA loop
Diagnose protocolreferences/protocols/diagnose.mdMental model matching, isolation sequence, OODA handoff conditions
Multi-source searchreferences/protocols/search-multi-source.mdQuery construction, source priority and the no-result fallback
Handoff to framingreferences/troubleshoot-to-frame-problem-llm.mdPassing an unresolved problem to frame-problem

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.