Scenario Playbooks

Scenario Playbooks

Status: Complete · [Contributions Welcome ✍️] — submit your own playbooks. The lifecycle applied to the situations you actually face.

Each playbook gives the Context Entropy, the personas involved, the steps, the gotchas, and done‑when criteria. They are starting points — adapt to your domain.

---

1 · Greenfield MVP (zero → deployed)

Entropy: High (13) overall, but decomposed into Low‑entropy slices · Personas: all four

1. Frame the product as 3–6 bounded contexts (e.g. auth, billing, dashboard). Draw the boundaries before writing a line.
2. Set up the Zero‑Ops stack and repo scaffold + .cursorrules.
3. Write the spec for the thinnest end‑to‑end slice first (usually auth + one core entity). Ship it before specing the rest.
4. Run the lifecycle per slice. Resist building horizontally ("all the schemas, then all the APIs").
5. Wire telemetry early so the self‑healing loop exists from day one.

Gotchas: Over‑specing the whole product up front (you'll rewrite it). Cross‑context coupling sneaking in before boundaries harden. Done when: A real user can complete the core journey on a deployed URL.

---

2 · New feature inside an existing bounded context

Entropy: Low (1–3) · Personas: Engineer, Guardian

1. Open the existing specs/<slice>.md. Edit the spec, don't touch code yet.
2. Prime the agent with only that slice + spec.
3. Generate the change as part of the slice; review the diff for drift.
4. Guardian runs the slice's existing tests + new edge cases.

Gotchas: The feature secretly needs another context's data → it's actually Scenario 3, not this one. Re‑classify. Done when: New behaviour + its edge cases are spec'd, tested, and shipped.

---

3 · Cross‑cutting feature (multiple contexts)

Entropy: Medium (5–8) · Personas: Conductor‑heavy, Engineer, Guardian

1. Identify every context the feature touches. Spec each context separately — do not merge them into one mega‑file.
2. Define the contract between contexts explicitly (event, shared type, or API) in the specs.
3. Generate one context at a time, reviewing the contract at each boundary.
4. Guardian tests the integration points hardest — that's where cross‑context bugs live.

Gotchas: Letting the agent reach across boundaries "for convenience" — that's how isolation rots. Keep contracts narrow. Done when: Each context's spec is current and the contract between them is tested end‑to‑end.

---

4 · Spec‑first bug fix

Entropy: usually Low — but check blast radius separately · Personas: Conductor, Engineer, Guardian

1. Reproduce. Write a failing test that captures the bug (Guardian).
2. Ask: does the spec describe the correct behaviour? If not, the spec is the bug — fix it there.
3. If the spec was right but the code drifted, regenerate the affected slice from the spec.
4. Confirm the failing test now passes and no others regressed.

Gotchas: Hand‑patching the code and never updating the spec — now the spec lies. A "low entropy" auth bug can be high blast radius; don't let the easy fix lower your guard. Done when: Bug has a regression test, and code + spec agree.

---

5 · Major refactor / framework migration

Entropy: High (13) · Personas: all four, slowly

1. Frame with a rollback plan. Migrations are where "move fast" goes to die — go deliberately.
2. Pin the target architecture in the spec before moving code. Define what "done" looks like per slice.
3. Migrate one bounded context at a time, keeping the app shippable between steps (strangler‑fig style).
4. Guardian maintains a parity test suite: old behaviour == new behaviour, slice by slice.
5. Stage the rollout; keep the old path behind a flag until parity is proven in production.

Gotchas: Big‑bang rewrites. Letting the spec describe the old world while code moves to the new one. Context windows can't hold a whole monolith — that's why you go slice‑by‑slice. Done when: Every context is on the new architecture, parity tests pass, old path removed.

---

6 · Third‑party / external API integration

Entropy: Medium–High · Personas: Engineer, Guardian

1. Spec the integration boundary: request/response shapes, auth, rate limits, and every failure mode (timeout, 4xx, 5xx, partial data, idempotency).
2. Isolate the integration in its own module so the vendor never leaks into your domain logic.
3. Guardian simulates hostile and degraded responses — the unhappy path is the whole point here.
4. Add telemetry on the integration specifically; external systems fail on their schedule, not yours.

Gotchas: Speccing only the happy path. No retry/idempotency strategy. Vendor lock‑in creeping into core logic — keep an adapter seam. Done when: The integration degrades gracefully under every failure mode you spec'd.

---

7 · Production incident response

Entropy: variable — triage first · Personas: Conductor, Engineer, Guardian

1. Stabilize before you fix: roll back or feature‑flag off the bad change. Restore service first.
2. Feed the captured stack trace / error payload into the self‑healing loop.
3. The agent cross‑references trace ↔ codebase and drafts a spec amendment (root cause), not a raw patch.
4. You review the amendment — never auto‑apply a fix to auth, payments, or data deletion.
5. Add a regression test that reproduces the incident before shipping the fix.

Gotchas: Auto‑healing a symptom while masking the real cause. Shipping the fix without a regression test, so it recurs. Done when: Service restored, root cause spec'd, regression test green, post‑incident note in Case Studies.

---

8 · Onboarding a legacy monolith

Entropy: High (13) · Personas: Conductor, Engineer

1. The monolith likely violates AI hygiene — don't expect clean generation against it yet.
2. Reverse‑engineer specs for the most active areas first (Engineer reads code → drafts spec → you correct it).
3. Carve out one bounded context at a time behind a clean seam; refactor toward small, cohesive files.
4. Only after a context is isolated and spec'd do you run the full lifecycle on it.

Gotchas: Pointing an agent at a 50k‑line file and expecting precision — accuracy collapses. Isolate first, then generate. Done when: At least one real context is isolated, spec'd, and changeable via the loop.

---

Reality check. These playbooks compress real work into tidy steps. Reality is messier — you'll discover a missing edge case at step 4, or find Scenario 2 was secretly Scenario 3. That's normal. The value isn't the linearity; it's knowing which scenario you're in so you apply the right entropy, personas, and gates. Misclassifying a high‑blast‑radius change as "quick and low entropy" is the most expensive mistake here.

---

Contribute a playbook: Use the structure above (Entropy · Personas · Steps · Gotchas · Done‑when) and add it via the wiki workflow.