--- name: "release_checklist" description: "Run a safe software release end to end: risk classification, pre-release gates, the go/no-go decision, staged rollout with bake times and decision thresholds, post-deploy smoke tests, release comms, and the post-release review. Use when shipping a version, preparing a deploy, or setting up release process." --- # Release Checklist ## Purpose Turn "is this release safe to ship?" from a gut feeling into a repeatable gate. This skill walks an agent through classifying the release, checking the pre-release gates, running a real go/no-go decision, rolling out in stages with metric thresholds, smoke-testing after deploy, sending the right comms, and reviewing afterward. It is built for an agent doing the release work itself, not for writing a doc about it. ## Workflow ### 1. Classify the release Set the risk class before anything else, because it decides the rollout shape: - **Routine**: additive changes, docs, small bug fixes, behind flags. Rollout: deploy to 100% after the go/no-go, standard watch. - **Significant**: user-visible behavior changes, API changes, migrations. Rollout: canary 1-5% with 15-30 min bake, then 25% / 50% / 100% stages. - **High-risk**: data model changes, auth/payment paths, large refactors, anything you cannot fully reason about. Rollout: 1% canary with longer bake (30-60 min), slow ramp, plus a rollback dry-run in staging first. Write the class down in the release notes. If you are unsure, pick one class higher. ### 2. Run the pre-release gates Every gate must pass before the go/no-go. A failing gate blocks the release, full stop. Work through this list and record evidence for each item (a CI link, a command output, a name), not just a checkmark: - [ ] Release candidate artifact built once, tested on staging, and that exact artifact is what ships. Never rebuild a different artifact for production. - [ ] All CI checks green on the release branch or tag (tests, lint, typecheck, security scan). - [ ] Smoke suite green against the release candidate on staging. - [ ] Database migrations: ordered, backward-compatible, and the rollback script dry-run on staging. Rolling deploys run old and new code side by side, so the migration must work with both. - [ ] Feature flags: risky features behind flags, defaults set, each flag has an owner and an expiration date. Every feature wants a kill switch. - [ ] Secrets, env vars, and runtime credentials already present in production scope. Never config-by-memory at deploy time. - [ ] Config diff reviewed: production vs staging differences are intentional and listed. - [ ] Cache invalidation plan defined (CDN, static assets, service caches) if anything cached changed. - [ ] Monitoring in place: dashboards or queries for error rate, latency (p50/p95/p99), saturation, and the business KPI this release touches. Baseline captured from before the release. - [ ] Rollback command written, tested, and one person named as rollback owner with a decision timeout (e.g. "if thresholds are not green in 10 minutes, roll back without a meeting"). - [ ] On-call engineer aware of the release window. Nobody ships while nobody is watching. - [ ] CHANGELOG updated with version and summary. API docs and migration notes updated if contracts changed. ### 3. Make the go/no-go call Hold the decision explicitly, even if you are the only one in the room. Produce a one-page release report: - Recommendation first: **GO**, **CONDITIONAL GO**, or **NO-GO**. - Scope of the release, links to test evidence, open defects and accepted risks (each with an owner and mitigation). - Rollout plan and rollback command. - Monitoring links. - Approvers. GO means every critical gate passed; non-critical gaps get an owner and a deadline. CONDITIONAL GO documents the conditions, their owners, deadlines, and an enhanced monitoring plan, and the release stops at the next stage until conditions clear. NO-GO means a critical gate failed: list the blockers with owners and set a re-review time. One NO-GO anywhere stops the ship. ### 4. Roll out in stages Deploy only through the approved CI/CD pipeline, never by hand. Follow the ladder for the risk class: - Deploy dark (0% traffic) and run post-deploy smoke against the production URL. - Canary: 1-5% traffic, bake 15-30 minutes (longer for high-risk). - Ramp: 25% -> 50% -> 100%, with bake time at each stage. At each stage, compare canary vs baseline on the same metrics. Use the decision thresholds in `references/rollout-thresholds.md`. New error signatures, not just higher rates, are an immediate flag: a brand-new error type in canary is a hold or roll back even if the overall rate looks fine. Watch dependency health too: downstream error rates and queue depths. For blue/green deploys, keep the old environment warm; switching back is the rollback. ### 5. Smoke-test after deploy Immediately after each deploy stage, run the smoke suite: health endpoint returns 200, readiness/startup probes pass, and the critical user journeys actually complete. Keep the checks idempotent so they can be rerun after retries. A starter script lives in `references/smoke-test.md`. Watch core alerts for at least 15 minutes after full rollout before closing the release thread. First-hour checklist: health 200, error dashboard clean, latency normal, critical flow tested manually once, logs flowing, rollback still verified. ### 6. Send the release comms Comms go out with every release, sized to the audience: - **Team**: release thread or channel message at deploy start, at full rollout, and at close. Include version, scope, rollout owner, and the monitoring link. - **Users**: release notes or changelog entry. For breaking changes, a migration guide. If there is a status page, post to it. - **On incident**: if production degrades, stop rollout activity and hand off to the incident protocol. Rollback is the default, not a failure. Templates for the common messages are in `references/comms-templates.md`. ### 7. Review the release 24-48 hours after full rollout, review: error budget burn vs expected, new error signatures, support ticket volume, crash-free rate, and the business KPI the release touched. Log the release in the release history with the DORA four: deployment frequency, lead time for changes, change failure rate, time to restore. Note what the checklist caught and what slipped past it, and fix the checklist. ## Output Contract A completed release produces, at minimum: 1. `release-notes.md`: version, risk class, scope, rollout owner, release thread link. 2. The pre-release gate list with evidence links per item. 3. The one-page release report ending in GO / CONDITIONAL GO / NO-GO. 4. The staged rollout log: stages, traffic percentages, bake times, metric readings per stage. 5. Post-deploy smoke results and the first-hour verification notes. 6. The comms that went out (team messages, release notes, status page posts). 7. Post-release review with DORA metrics and checklist improvements. If you cannot produce all seven, say which are missing and why. A release that cannot show its evidence did not pass its gates. ## Operating Rules 1. One failing critical gate is a NO-GO. No "probably fine", no shipping on hope. 2. The artifact tested in staging is the artifact shipped. Rebuilds mean retesting. 3. Every risky feature ships behind a flag with an owner and an expiration date. Test both flag states in CI. 4. Migrations are backward-compatible and additive only. The rollback script gets a dry run on staging before production. 5. Bake times and thresholds are set before the rollout starts, from `references/rollout-thresholds.md` defaults adjusted to the service. Do not invent them mid-deploy. 6. Someone watches the first hour. A release with no one watching is a NO-GO. 7. Roll back immediately on: error rate above 2x baseline, p95 latency up more than 50%, a spike in user reports, any data-integrity issue, any security issue. Rolling back is not failure; shipping broken is. 8. Friday-afternoon ships of anything above Routine class are a NO-GO by default.