pantheon-ai/troubleshoot
Search-first troubleshooting with a diagnostic phase — use when an error, bug, or unexpected behaviour is reported.
75
75%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
reference.mdreferences/
Troubleshoot Reference
1. Isolation Techniques
Wolf Fence (Binary Search)
Divide and conquer. Cut search space in half each step.
| Step | Action |
|---|---|
| 1 | Comment out / disable half the code |
| 2 | Bug gone? → It's in removed half. Bug persists? → Other half |
| 3 | Repeat on guilty half until single line/block found |
Git variant: git bisect start → git bisect bad → git bisect good <commit> → Git finds guilty commit in O(log n)
Swap One Variable
When multiple suspects, change only one at a time:
- Works in env A but not B? → Diff A and B
- Works with data X but not Y? → Diff X and Y
- Works before commit Z? → Diff before/after Z
Minimal Reproduction
Reduce to smallest case that still fails:
- Remove code/config until bug disappears
- Add back last removed piece
- That's your culprit
2. Root Cause Drilling
5 Whys
Keep asking "why?" until you hit root cause (usually 3-5 levels):
Problem: API returns 500
→ Why? Unhandled exception
→ Why? Null pointer on user.email
→ Why? User record has no email
→ Why? Migration didn't backfill
→ Why? Script assumed all users have email ← ROOT CAUSERule: Stop when answer is actionable fix.
Fishbone (6 M's)
For complex bugs with unclear cause, brainstorm across categories:
| Category | Questions |
|---|---|
| Man | Who touched it last? Training gap? Handoff issue? |
| Machine | Hardware? Memory? CPU? Disk? Network? |
| Method | Process flaw? Missing step? Wrong order? |
| Material | Bad input data? Corrupt file? Wrong format? |
| Measurement | Missing logs? Wrong metric? Alert gap? |
| Milieu | Environment diff? Config drift? External dep? |
Pick 2-3 most likely categories, investigate those first.
3. Assumption Surfacing
Rubber Duck
Explain the problem out loud, line by line:
- "This function should do X..."
- "First it gets Y from Z..."
- "Then it— wait, that's not what it does"
Why it works: Forces you to articulate assumptions. Bug often surfaces mid-explanation.
Verify → Shorten → Reveal
| Phase | Action |
|---|---|
| Verify | Does bug actually exist as reported? Reproduce first. |
| Shorten | Make feedback loop fast (seconds not minutes). Write a test. |
| Reveal | Add logging at boundaries. Test each assumption explicitly. |
4. Investigation Loop (OODA)
When isolation + drilling doesn't resolve:
OBSERVE → ORIENT → DECIDE → ACT → repeat| Phase | Action | Example |
|---|---|---|
| Observe | Gather data | "Run X and paste output" |
| Orient | Form hypothesis | "This suggests Y because..." |
| Decide | Pick next action | "Let's verify by checking Z" |
| Act | User executes | "Run this command: ..." |
Exit when: Root cause confirmed + fix verified
Stuck? Go back to Search (step 1 in SKILL.md) with new keywords from investigation.