| name | troubleshooting-whats-not-working |
| description | Use when something is broken, failing, or not behaving as expected (any domain - software, gadget, process, plan) |
| kind | workflow |
| audience | anyone |
| ai-tools | any |
| complexity | guided |
| time | 10-30 min |
| version | 1.0.0 |
| source | bundled |
Troubleshooting What's Not Working
What this does
Walks you from "something is wrong" to a verified diagnosis using evidence, not guesses. Works for software bugs, broken appliances, stalled projects, or interpersonal issues.
When to use
- Something stopped working that used to work
- Something is producing the wrong result
- A plan isn't going as expected and you can't tell why
What you bring (Inputs)
- Description of what you expected to happen
- Description of what actually happened
- When it last worked / when the symptom started
What you get (Output)
A diagnosis (the cause) plus a verified fix attempt or, if unfixable yet, a clear "next thing to test."
How it works (Steps)
This is a guided workflow.
Stages
Stage 1: State the symptom precisely
Write one sentence: "When X, I expect Y, but I get Z." If you can't write this sentence, the symptom isn't precise enough yet. Sharpen.
Stage 2: Capture the recent change
What changed since this last worked? Be specific: "I updated the app" or "we moved offices" or "she started a new job." If "nothing changed," challenge that — something always did.
Stage 3: Bisect
Find the smallest scenario that still produces the symptom. Strip away anything optional. The smaller the failing case, the easier the cause is to see.
Stage 4: Form one hypothesis
State: "I think the cause is X because of evidence Y." One hypothesis at a time.
Stage 5: Test the hypothesis
Design a check that would prove the hypothesis wrong if it's wrong. Run the check. Record what you observed.
Stage 6: Decide
- Hypothesis confirmed → proceed to fix and verify the fix actually fixed it
- Hypothesis disproved → return to Stage 4 with a new hypothesis (don't recycle the old one)
- Hypothesis inconclusive → tighten the test in Stage 5
Stage 7: Verify the fix
After fixing: reproduce the original symptom scenario. The symptom must be gone. Otherwise the fix didn't fix it (despite what you'd like to believe).
Checkpoints
- After Stage 1: symptom is one sentence, with expected vs actual
- After Stage 2: at least one change identified
- After Stage 3: smallest failing case noted
- After Stage 4: one hypothesis with named evidence
- After Stage 5: test was actually run; result recorded
- After Stage 7: original symptom no longer reproducible
Loop-back conditions
Return to Stage 4 when a hypothesis is disproved.
Return to Stage 1 when bisection reveals the symptom statement was wrong.
Quality bar
- Symptom statement is precise and falsifiable
- One hypothesis at a time (not "could be A, B, or C")
- Fix is verified by reproducing the original case
- If unfixable today, there's a clear next test
Variations
- Software bug: Stage 5 test is usually a runnable script or command
- Broken appliance: Stage 5 test might require a multimeter or replacement part
- Process problem: Stage 5 test might be "run it once with the proposed change and observe"
- Interpersonal: hypothesis is about motivation; test is a clarifying conversation, not a confrontation
Example
Input: My monthly invoice automation worked all year, last week it sent invoices to the wrong customers.
- Stage 1: "When the cron runs on the 1st, I expect each invoice to go to its own customer; it's going to the previous customer in the list."
- Stage 2: "Last week the dev updated the lookup library."
- Stage 3: Smallest failing case: 2 customers, both got each other's invoice.
- Stage 4: Hypothesis: the lookup change introduced an off-by-one.
- Stage 5: Run with library version pinned back to last month. Symptom gone.
- Stage 6: Hypothesis confirmed.
- Stage 7: Fix is to either roll back or patch. After patch, run with 5 test customers. Symptom stays gone.
