---
name: troubleshooting-guide
description: >-
  Creates systematic troubleshooting guides and runbooks with structured diagnostic
  steps. Use when documenting common support issues, creating operations runbooks,
  or building diagnostic workflows for known failure modes.
  NOT for actively debugging live issues, writing tests, or post-incident root cause analysis.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---
## Identity & Scope
**Executor:** either  **Model tier:** sonnet
**Scope:** Application logs, error messages, config files, source code, existing docs, monitoring outputs
**Off-limits:** Modifying production systems, restarting services, applying fixes, accessing live databases
### Hard Rules
- No credentials in output or git — ever
- No spending money without explicit user approval
- No deleting files — archive first, 48hr hold
- No killing processes without explicit instruction
- Report completion to boss via structured output
## Essential Principles
1. **Most common cause first** — Order diagnostics by frequency. The boring fix that works 80% of the time goes first. Guards against: chasing edge cases while users are stuck on the obvious.
2. **Every step must be copy-pasteable** — Exact commands, not prose. `tail -100 /var/log/app/error.log | grep "ConnectionRefused"` not "check the logs." Guards against: vague instructions requiring prior knowledge.
3. **Show expected output** — Every diagnostic states what correct looks like. Guards against: users running commands but not knowing how to interpret results.
4. **Always end with escalation** — When the guide fails, name who to contact and what info to include. Guards against: dead-end troubleshooting.
## When to Use
- Documenting common support issues and resolutions
- Creating operational runbooks for on-call engineers
- Building diagnostic guides for known failure modes
- "Help me troubleshoot X" / "Create a runbook for Y"
- Documenting post-incident resolution for future reference
## When NOT to Use
- Actively debugging a live issue — use incident response runbooks instead
- Post-incident root cause analysis — use `retrospective-analysis` instead
- Writing automated tests — use testing skills instead
- Designing monitoring/alerting — use observability skills instead
- Fixing a specific code bug — use debugging/code review skills instead
## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "I'll list causes alphabetically" | Frequency ordering saves time — first diagnostic should fix 80% of cases |
| "Users will know how to interpret the output" | Unexplained output is useless — always state what healthy looks like |
| "Escalation path is obvious" | Without explicit escalation, users loop through failed steps |
| "Generic commands work everywhere" | Platform-specific commands work immediately; generic ones need translation |
| "One big guide covers everything" | Symptom-based entries let users find their issue fast |
## Workflow
### Phase 1: Problem Inventory
**Entry:** User has specified a system or set of issues to document
**Actions:**
1. Glob for error handling, logging, and error message definitions
2. Grep for common error patterns, exception types, exit codes
3. Read existing documentation, FAQs, known-issues files
4. Identify most common failure modes from error handling code
5. Categorize by symptom (what the user sees)
**Exit:** Problem inventory organized by user-visible symptom
### Phase 2: Diagnostic Design
**Entry:** Problem inventory exists
**Actions:**
1. For each problem, identify the "quick check" — single most likely fix
2. Design ordered diagnostic steps: most common cause to least common
3. Write exact commands with expected output (healthy vs. unhealthy)
4. Build cause table: cause, how to confirm, exact fix steps
5. Define escalation path: who, what logs to include, expected response time
**Exit:** Complete diagnostic workflow for each problem
### Phase 3: Guide Assembly
**Entry:** Diagnostic workflows designed
**Actions:**
1. Write each entry: Problem, Quick Check, Diagnostic Steps, Causes table, Escalation
2. Ensure every command is platform-specific and copy-pasteable
3. Add expected output examples (success + failure) for every diagnostic
4. Cross-reference related problems ("If this didn't help, see: [Problem Y]")
5. Add index/table of contents by symptom keyword
**Exit:** Complete troubleshooting guide document
### Phase 4: Verification
**Entry:** Guide assembly complete
**Actions:**
1. Verify every diagnostic step has an exact command (not prose)
2. Confirm every command shows expected output for healthy and unhealthy
3. Check every entry ends with escalation path (who, what info, when)
4. Validate problems ordered by symptom with most common causes first
5. Ensure no credentials or secrets in examples
**Exit:** All checks pass — output results
## Output Format
```json
{
  "skill": "troubleshooting-guide",
  "status": "completed",
  "worker": "worker-id",
  "summary": "8 common issues documented for Memory API. 24 diagnostic steps, all copy-pasteable.",
  "findings": [
    {"item": "Connection refused on port 8001", "severity": "info", "detail": "3 steps, 4 causes. Quick check: systemctl status."},
    {"item": "Search returns empty results", "severity": "info", "detail": "5 steps: embedding model, index state, query format. Common: unbuilt index after import."},
    {"item": "Gap: No error codes in API responses", "severity": "medium", "detail": "API returns generic 500s. Diagnostics rely on log parsing. Recommend structured errors."}
  ],
  "problems_documented": 8,
  "total_diagnostic_steps": 24,
  "artifacts": ["docs/troubleshooting.md"],
  "errors": [], "elapsed_seconds": 65.4
}
```
### Bad Example
```json
{"skill": "troubleshooting-guide", "summary": "Guide created", "findings": [{"item": "Documented issues", "severity": "info", "detail": "Covers main problems"}]}
```
Wrong: No problem count, no specifics, no step count. Boss cannot evaluate coverage.
## Escalation Triggers
STOP and report to boss (do NOT guess) when:
- [ ] System has no logging or error handling to build diagnostics from
- [ ] Active security issues discovered while analyzing errors
- [ ] Troubleshooting requires access to production systems
- [ ] Error messages contain credentials or secrets needing redaction
- [ ] Failure modes undocumented and require running the system to discover
- [ ] Failed to identify common failures after 3 search strategies

Escalate as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`
## Success Criteria
- [ ] Each problem has: symptom, quick check, ordered diagnostics, cause table, escalation
- [ ] Every diagnostic command is exact and copy-pasteable
- [ ] Every command shows expected output (healthy + unhealthy)
- [ ] Problems ordered by symptom, most common causes first
- [ ] No credentials or secrets in examples
- [ ] Output matches the JSON format above
- [ ] No escalation triggers hit (or all reported)
