Expect The Unexpected

Expect the Unexpected

Overview

Scenario-driven failure-mode analysis. Given one specific scenario, trace its execution path and systematically surface what could break — ranked by risk, each with a concrete mitigation or a test to write.

Core principle: Forward reasoning misses things. Walk a fixed taxonomy against the path AND run a pre-mortem ("assume it already failed in prod"). The two passes catch different failures.

Capabilities

Reasoning mode (default). Two analysis paths: (a) the user gives one scenario → trace and analyze it; (b) the user gives a bounded surface but no scenario → generate the scenarios worth tracing, rank them, let the user pick, then analyze each. Either way: predict failures and generate test cases for the user to run. Do not execute tests, run code, or modify files.

Execution mode (opt-in). After the FMEA table and coverage note, offer to write the selected test cases as real test files and run them with the project's own test runner — reporting a per-row verdict (CONFIRMED / NOT REPRODUCED / INCONCLUSIVE) and offering a fix for each confirmed failure, one at a time, each requiring user approval. Entered ONLY on explicit user acceptance (see Step 6). In read-only hosts/modes, skip the offer; reasoning mode stands alone. External dependencies are mocked via the project's existing test stack (Jest/Vitest vi.mock, pytest monkeypatch/unittest.mock, gomock, etc.) — never live APIs or destructive real-data operations. See references/execution-mode.md for the trust boundary.

Optional pre-deploy hook (Cursor, Claude Code, …): see extensions/pre-deploy-gate/README.md.

When to Use

• "What could go wrong if…" / "what breaks when…" for a named scenario
• "Pressure-test / stress-test / red-team this path before we ship"
• Pre-launch / pre-deploy gut-check on a feature or endpoint
• Design-time review: a proposed flow, no code yet
• A bounded surface (a diff/PR, file, endpoint, or feature) but no scenario yet — Stage 0 generates the candidate scenarios for you

Do NOT use when: the user wants a whole-repo review or open-ended bug hunt with no scenario. Route that to a code-review skill instead.

Routing

| User gives… | Do | |-------------|-----| | A specific scenario | Skip to the per-scenario flow below (Steps 1–6). | | A bounded surface, no scenario | Run Stage 0 (scenario generation), then Steps 1–6 per chosen scenario. | | Nothing / "review my whole repo" | Refuse — ask for a bounded surface (a diff, file, endpoint, or feature). |

Stage 0 — generate scenarios (when no scenario was given)

The user has a bounded surface (usually a diff/PR, or a file, endpoint, or feature description) but doesn't know what to fear. READ references/scenario-generation.md now and follow it: gather the surface → extract risk anchors → run the taxonomy in reverse as a scenario generator → rank by blast radius × plausibility → present a ranked menu of ~5–8 concrete scenarios → let the user pick ("top N" is valid). See examples/checkout-diff-stage0/ for a worked menu. Then run Steps 1–6 below on each chosen scenario.

Per-scenario flow (Steps 1–6)

1. Pin down the scenario

The scenario is the primary input. If the user gave code but no scenario, do not analyze a whole file blindly — go to Routing above.

Then state the execution path you will trace in 1-3 lines: entry point → key steps → external calls → side effects → response. This anchors the analysis.

2. Walk the failure taxonomy

READ references/failure-taxonomy.md now and walk every category against this scenario's path. The 8 categories (one-line gloss — full prompts in the reference):

| # | Category | Gloss | |---|----------|-------| | 1 | Inputs | Untrusted data shape, size, encoding | | 2 | State & timing | Races, retries, ordering, partial work | | 3 | External dependencies | Timeouts, outages, bad responses | | 4 | Resources & scale | Volume, memory, pools, cost blowups | | 5 | Auth & security | Access control on this path | | 6 | Time | Clocks, timezones, expiry, DST | | 7 | Money / SaaS | Payments, webhooks, billing drift | | 8 | Failure of the failure | Broken error handling / recovery |

Skip a category only after confirming it does not touch this path.

3. Pre-mortem pass

After the forward walk, run this prompt explicitly:

> "Assume this scenario has ALREADY caused a catastrophic, customer-visible > failure in production. Narrate exactly what happened, step by step."

Use the narration to catch failures the forward walk missed. Add any new ones to the findings.

4. Output FMEA-style, ranked by risk

For each failure mode, one row:

| Failure mode | Trigger | Symptom | Likelihood | Impact | Risk | Mitigation / Test to write |

• Likelihood and Impact: Low / Med / High.
• Risk: combined rating used to sort — highest risk on top. Use this matrix

(do not improvise):

| Likelihood ↓ / Impact → | Low | Med | High | |---------------------------|-----|-----|------| | Low | Low | Low | Med | | Med | Low | Med | High | | High | Med | High | High |

• Mitigation / Test: a concrete fix OR a specific test case the user can

write (inputs + expected behavior). Prefer a test when the fix is unclear.

Group nothing; just rank. Lead with the top 3-5 so the user sees what matters. See examples/ for worked input → output samples.

5. Coverage note (REQUIRED — end every run with this)

Always close with, verbatim in spirit:

> "These are known failure classes for this path; this is not proof of > correctness. Untested classes and anything outside this scenario remain > unverified."

If Stage 0 ran, also note: scenarios that were generated but not selected, and any surface area dropped by the cap, remain unanalyzed.

Never imply the software is now safe or "done."

6. Offer execution (opt-in)

If the host can write files and run commands, append one line after the coverage note:

> "Want me to write and run tests for any of these failure modes?"

If the user accepts, have them pick rows if they haven't ("top N" is valid), then READ references/execution-mode.md now and follow it. If the user declines, or the host is read-only, the run ends here — a pure reasoning-mode run.

Quick Reference

| Step | Do | Don't | |------|-----|-------| | Input | Require a scenario OR a bounded surface | Analyze whole repo | | Generate | Stage 0: surface → ranked scenario menu | Invent scenarios with no surface | | Trace | State the path first | Jump to findings | | Taxonomy | Read the reference, walk all 8 | Rely on memory | | Pre-mortem | Narrate the prod disaster | Skip it (forward-only misses things) | | Output | FMEA table ranked by risk | Unranked wall of text | | Code/tests | Suggest tests; write/run them only in execution mode after opt-in | Execute or fix anything without the explicit opt-in | | Close | Coverage caveat | Claim it's safe |

Common Mistakes

• No scenario → analyzing the whole file anyway. Don't. Either run Stage 0

to generate scenarios from the bounded surface, or ask for a bounded surface.

• Generating without a surface. Stage 0 needs a fence (diff, file, endpoint,

feature). Inventing scenarios from nothing = the whole-repo hunt this skill refuses.

• Menu of vague scenarios. Each generated scenario must be concrete and

traceable ("the webhook fires twice"), anchored to a real entry point/side effect — never a category label ("check inputs").

• Forward-only. Skipping the pre-mortem is the #1 way real failures slip

through. Do both passes.

• Vague mitigations ("add validation"). Name the input and the expected

behavior, or write the actual test case.

• Unranked output. The user needs the highest-risk items first.
• Overreach. Reasoning mode does not run tests or change code. Enter

execution mode only after the user explicitly accepts the Step 6 offer — never uninvited, and never by skipping the FMEA output.

• Treating NOT REPRODUCED as proof. A passing generated test is evidence

the failure wasn't observed under that test — not proof the failure mode is absent.

• False assurance. Always end with the coverage caveat.

See README.md for install paths and optional extensions.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 008993368-yaz
• Source: 008993368-yaz/expect-the-unexpected
• License: MIT

Install and usage instructions live in the source repository linked above.