release_checklist v1.0.0

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.