Release readiness

Release-Readiness Gate Playbook

Authored by Claude Fable 5. The purpose of this skill is to be the last honest voice before a deploy. Its only failure mode that matters is a false GO — so every "pass" must be something you observed, never something you assumed.

Why this exists

The moment before shipping is when optimism peaks and diligence drops. Unguided, a model will read the code, see nothing obviously wrong, and say "looks good to ship" — which is a guess wearing a green checkmark. This playbook converts "looks good" into "I ran it and here's what I saw," and gives a verdict the user can act on without re-checking.

Phase 0 — Establish what "shipping" means here

Read CLAUDE.md / WORK_STATUS.md for the deploy process and any release conventions. Know: what command deploys, where it goes, whether users get it immediately (and via what mechanism — a service-worker update banner, an app store, a CDN), and whether there's a rollback path. You can't gate a release you don't understand the shape of.

Phase 1 — The mechanical gates (must all pass)

These are pass/fail and non-negotiable. Run each, record the actual result:

1. Build passes. Run the real build command. A green build is table stakes; a red build is an instant NO-GO. Paste the relevant output.
2. Types/lint clean (if the project uses them). Run them. Warnings the project treats as errors count as failures.
3. Tests pass (if they exist). Run the suite. Note anything skipped.
4. No debug residue. Grep for leftover console.log, debugger, commented -out blocks, TODO: remove, hardcoded test data, or a stray "test" list/user that shouldn't ship.

Gate: if any mechanical gate fails, you're already at NO-GO. Record the failure and continue gathering the rest anyway — the user deserves the full picture, not just the first blocker.

Phase 2 — The behavior gates (verify the core flows)

A green build that crashes on load has passed nothing that matters. Actually exercise the product's critical paths — the two or three flows that, if broken, mean the release is a failure regardless of what else works. Follow any repo-specific run instructions (e.g. local/signed-out mode).

For each critical flow: run it, observe it, record what you saw (a screenshot or the concrete result). Check specifically:

• Does the app load without console errors?
• Does the primary happy path complete end to end?
• Did this release's changes actually do what they were supposed to? (Verify the feature you're shipping, in the running app — not in the diff.)
• Any obvious regression in the areas the change touched?

Gate: the change you're shipping must be observed working in the running build. "The code looks right" does not clear this gate.

Phase 3 — The hygiene gates (should pass)

Lower stakes, but a mature release checks them:

• Version notes / changelog / WORK_STATUS.md updated to reflect what's shipping?
• Docs updated if behavior or setup changed?
• New env vars / config / secrets documented and present in the deploy target? (A feature that works locally because of a .env.local the server doesn't have is a classic post-deploy failure.)
• Migrations / data shape changes accounted for?

Phase 4 — Verdict

Give a single clear verdict up top, then the evidence:

# Release Readiness — <what's shipping> — <date>

## Verdict: GO / NO-GO / GO-WITH-CAVEATS
<one sentence stating the call and the single most important reason>

## Mechanical gates
- [x] Build — <result / output snippet>
- [x] Types/lint — <result>
- [ ] Tests — <result, or "none in project">
- [x] No debug residue — <result>

## Behavior gates
- [x] App loads clean — <evidence>
- [x] <critical flow> — <evidence / screenshot>
- [x] This release's change verified working — <what you saw>

## Hygiene gates
- <status of version notes, docs, env, migrations>

## Blockers (if NO-GO)
<numbered, each with what to fix>

## Caveats (if GO-WITH-CAVEATS)
<known-but-acceptable issues the user is choosing to ship with, stated plainly>

Phase 5 — Hand back the decision

Deliver the verdict and do not deploy yourself unless the user explicitly tells you to — deploying is outward-facing and irreversible-ish, and the GO call is theirs to confirm. If it's a NO-GO, offer to fix the blockers. Never upgrade a NO-GO to a GO because the fixes look small or the user seems eager; the whole value of a gate is that it doesn't bend under pressure.