# Release and close out > Whatever the client's process, ship the version you verified, know how to undo it, and leave the docs true. Deploy and release · /release-mgmt/ · 2026-11-05 ## 1. Prepare the release record **Codex** ```text $neutron:release-check Prepare the release record for [release version] on [release branch]. Production runs [previous production commit]. Read each ticket in the Jira fix version, with its acceptance criteria and comments, through the connected Jira MCP or authenticated acli. Match the tickets to the merged PRs both ways, and read the repository release runbook. Patch-release tickets merged in from main are expected; list them separately. If Jira access is unavailable, ask for the ticket list with pasted details. Report each mismatch, verification gaps, the tested artifact, and every migration, configuration, schedule or external-call change with how it is undone. Do not deploy or change any environment. ``` **Claude Code** ```text /release-check Prepare the release record for [release version] on [release branch]. Production runs [previous production commit]. Read each ticket in the Jira fix version, with its acceptance criteria and comments, through the connected Jira MCP or authenticated acli. Match the tickets to the merged PRs both ways, and read the repository release runbook. Patch-release tickets merged in from main are expected; list them separately. If Jira access is unavailable, ask for the ticket list with pasted details. Report each mismatch, verification gaps, the tested artifact, and every migration, configuration, schedule or external-call change with how it is undone. Do not deploy or change any environment. ``` - Start from the merged tickets, remaining checks and recovery notes handed over by [Code review](/code-review/). - Resolve every mismatch with the PM before validation: finish or move a ticket that has no merged PR; ticket a change that has none, or take it out by [rebuilding the candidate](/branching-strategy/#remove-a-ticket-by-rebuilding-the-candidate). - Check the agent's summary against the actual diff, and explain every skipped test or report-only scan. * **REL-8** (high risk; checked by code review): **The release branch holds exactly the tickets in the Jira fix version, no more and no less.** The one exception is patch-release tickets that arrive by merging `main`. Match merged PRs to tickets both ways before validation, and resolve every mismatch first. * **REL-5** (high risk; checked by code review): **Deploy the exact artifact that passed validation.** Promote it by digest or signed build. A rebuild, or any change to the candidate, needs new evidence and new approval. > **Example: ENG-123 · Release record** > > | Record | Content | > | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Version | `release/2.8.0` at `7d03f5b`; production runs `2.7.1` at `a41c9e2`. Image digest `sha256:9f2c…`; target: production. | > | Evidence | CI run for `7d03f5b`. CSV contents, merchant isolation and existing filters verified in staging. | > | Remaining gap | Export time at production volume is unmeasured; resolve before promotion. | > | Recovery | Pause the export queue, then redeploy the `2.7.1` image; the additive exports table stays. A leaked export also needs [incident handling](/incidents/). | > | Success check | Export success rate and latency for 30 minutes after deploy; owner named. | ## 2. Plan how each change is undone - **REL-6** (high risk; checked by code review): **Plan recovery for each change before deploying.** Name how it is undone and who decides. A code rollback does not undo migrations, data changes, sent messages or payments. | Change | How it is undone | What stays behind | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Backend code | Redeploy the previous artifact. | Jobs queued by the new version may fail on the old code. | | Behaviour behind a flag | Turn the flag off; no deploy needed. | Data written while it was on. | | Schema | Keep compatible additions when rolling code back. See [Database changes](/migrations/). | Dropped data: a down migration won't bring it back. | | Data change or backfill | A repair, tested on a copy. For value, new correcting ledger entries. | Changed rows and their external effects. | | Messages, payments, partner orders | Not reversible by rollback. Establish each outcome, then cancel or compensate where the provider allows, through [Investigate and recover](/incidents/). | Effects that are done, pending or unknown. Provider acceptance is not the customer outcome. | | Mobile build | Cannot be recalled. Switch the feature off on the server, or ship a new build through store review. | Installed builds keep calling the API until users update. | If a change can only be fixed forward, decide before deploying how you will contain it, such as switching the feature off or pausing new work. ## 3. Release through the project's process - Follow the project's release runbook for approval, timing and deployment. The PM gates the release after checking with the client, QA and developers. - Bring the release record to that approval. It covers what change requests usually ask for: version, evidence, risk and recovery. - Before go-live or a major release, the [SSAT](/ssat/) is checked with evidence for every applicable line. - Deploy only the approved artifact. For mobile that is the signed store build, with its version, configuration and distribution target checked. - An urgent fix takes the same steps on its patch release. The record can be short; it can't be skipped. Scenario: release 2.8.0 has just been deployed. **Bad prompt** ```text Check that production is healthy after the deploy. ``` **Better prompt** ```text Verify [release version] in [environment] using approved read access. Confirm the running version and artifact digest, then check [changed flow] and its success metrics over [observation window]. Report what you checked, failing checks, and pending jobs or partner outcomes. Do not restart, roll back or change configuration. ``` Why: a healthy server says nothing about the feature. Confirm the version that is running, then the changed flow and its pending work. - If a success check fails, stop the rollout, use the recovery plan, and take unresolved impact to [Investigate and recover](/incidents/). ### Ship a mobile build - Let the pipeline set the version and build number. A hand-edited version can go backwards, and the store rejects it or a newer build hides it. - Build separate test and production variants, each with its own app ID and configuration, and check which one you are submitting. - Plan for store review time; a fix to a released build waits for review too. - Release to a small share of users first where the store allows it, and know how to halt the rollout. - If the project ships over-the-air updates, send them only to builds whose native code they match. A change to native code, permissions or the app's configuration needs a store build. - Keep the backend [backwards compatible](/deliver-a-change/#r-api-1) with every version still allowed to run, and move the forced-update setting only when users can update. ## 4. Merge back and align the docs - After production verification, the tech lead merges the release branch into `main` by reviewed PR, so new work starts from what is running. - Then cut a docs branch from `main` and run the closeout skill: **Codex** ```text $neutron:release-closeout Align the docs on main with the code for [release version]; the previous production commit is [previous production commit]. Inventory every doc file against the docs index and the code: correct, add, merge, move or delete. If anything needs changing, open a docs-only PR with a table of each file, its action and the reason; otherwise report the files inspected and the evidence. Do not merge. ``` **Claude Code** ```text /release-closeout Align the docs on main with the code for [release version]; the previous production commit is [previous production commit]. Inventory every doc file against the docs index and the code: correct, add, merge, move or delete. If anything needs changing, open a docs-only PR with a table of each file, its action and the reason; otherwise report the files inspected and the evidence. Do not merge. ``` - Agents leave plans, summaries and analyses behind, and a doc that describes nothing current misleads the next agent more than a missing one. Delete instead of archiving: git history and the ticket keep the context. - The release diff shows where content drifted; the full inventory catches orphans from earlier releases. - Review the PR's file table first, then the content. It changes docs only. - Ticket anything left over in Jira. When nothing needs changing, attach the inspection record to the release's ticket. * **REL-1** (medium risk; checked by code review): **After every release, align the docs with the code on `main`.** Correct what drifted, add what is missing, restructure where needed, and delete docs that no longer describe anything current. That includes the README, runbooks, `AGENTS.md` and `CLAUDE.md`. Caution: If `CLAUDE.md` holds more than `@AGENTS.md`, move the extra lines into `AGENTS.md`. * **REL-7** (medium risk; checked by code review): **Every doc file is listed in the repository's docs index with its purpose.** Keep the index in `AGENTS.md` or a file it points to. At closeout, a doc nobody can place is deleted or merged; git history is the archive. * **REL-4** (medium risk; checked by code review): **Agent files describe how to work in the repo today.** They aren't a changelog. Remove stale lines in the same pass. * **REL-3** (low risk; nothing checks this yet): **Merge closeout corrections before cutting the next release branch** so it inherits current instructions. If no correction is needed, record the evidence. Next: If a success check fails or users report a problem, take the release record to [Investigate and recover](/incidents/).