跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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.

digital-stoic-org · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add digital-stoic-org/agent-skills --skill troubleshoot

技能说明


name: troubleshoot description: "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." allowed-tools: WebSearch, WebFetch, AskUserQuestion, Read, Glob, Grep model: opus context: main argument-hint: cynefin-domain: complicated cynefin-verb: analyze

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