# Troubleshoot

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

- Skill: `digital-stoic-org/troubleshoot` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add digital-stoic-org/troubleshoot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/digital-stoic-org/troubleshoot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: digital-stoic-org (https://skillmd.com/u/digital-stoic-org)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/digital-stoic-org/troubleshoot

---


# Troubleshoot

Search-first diagnostic workflow. Human executes commands.

## ⚠️ AskUserQuestion Guard

**CRITICAL**: After EVERY `AskUserQuestion` call, check if answers are empty/blank. Known Claude Code 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 Claude Code 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

Read `$PRAXIS_DIR/reference/troubleshoot/learnings.yaml` if exists. Apply known patterns before searching.

### 1. Search (do first)

80% of bugs solved online.

- WebSearch: `[error] [stack] [framework]` on SO, GitHub, Docs, Reddit
- 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 `protocols/diagnose.md` for details.

1. **Mental models**: Check learnings.yaml → WebSearch pattern → reason with 5 Whys/Fishbone
2. **Isolation**: Wolf Fence (binary search), swap one variable, minimal repro
3. **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.**

Persist the diagnostic session to `$PRAXIS_DIR/thinking/troubleshoot/{project}/{date}-{slug}-llm.md`.

`{project}` = current project folder name. `{slug}` = lowercase hyphenated from primary symptom/error. Create directory if missing.

**Collision handling**: If filename exists, append sequence: `{date}-{slug}-2-llm.md`, `{date}-{slug}-3-llm.md`. First write gets clean name.

**Guard**: If `$PRAXIS_DIR` is unset, skip artifact persistence silently (troubleshooting must not fail because of missing env var).

**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 `learnings.yaml` which captures distilled, reusable conclusions.

### 6. Learn

After resolution, AskUserQuestion: "Save this learning?"
- Global → append to `$PRAXIS_DIR/reference/troubleshoot/learnings.yaml`
- Project → append with `scope: project:<name>`
- Skip

## ✅ Completion Checklist

Before responding to user, verify:
- [ ] Artifact written to `$PRAXIS_DIR/thinking` (or guard triggered if unset)

## Refs

- `protocols/diagnose.md` - Mental models, bisect strategies