Release spec
This template is not tied to a playbook stage. Also used in Release spec for one release or significant change
Download release-spec.md — the source, as in the repository.
How to use
The template's own instructions:
Template from the UASK Engineering Hub, item process.release-spec. Save as project/specs/RS-NNN.md (or beside the release plan). Write it before Build starts and get it approved at gate G2. Sections that need a tier say so in their first line; a section that does not apply says "none" and stays. Delete these comments when a section is written.
Fields
Front-matter fields and sections of the document the template creates. A section marked Optional in the template may be deleted from a copy; every other field and section stays (tools/check_artifacts.py checks this for the kinds it knows).
| Field or section | Where | Required |
|---|---|---|
template | front matter | required |
id | front matter | required |
title | front matter | required |
status | front matter | required |
version | front matter | required |
tier | front matter | required |
appetite | front matter | required |
approver | front matter | required |
prd | front matter | required |
blueprint | front matter | required |
date | front matter | required |
| 1. Context and scope | section | required |
| 2. Goals and non-goals | section | required |
| 3. Design | section | required |
| 4. Alternatives considered | section | required |
| 5. Cross-cutting impact | section | required |
| 6. Acceptance and verification | section | required |
| 7. Rollout and rollback | section | required |
| 8. Work packages | section | required |
| 9. Risks and rabbit holes | section | required |
| 10. Open questions | section | required |
| Close-out | section | optional |
Example
A filled-in copy for an invented product, templates/examples/release-spec.md, in the Hub repository.It shows the level of detail to aim for, not text to reuse.
---template: release-spec/1id: RS-001title: Release spec — Offline notesstatus: draftversion: 0.1.0tier: standardappetite: 4 agent-daysapprover: leadprd: project/PRD.md@0.1.0blueprint: project/BLUEPRINT.md@0.1.0date: 2026-03-10---
# Release spec — Offline notes
## 1. Context and scope
First release that a tester can use: write, save and reopen a note with no network. Builds on the foundation (M0).
## 2. Goals and non-goals
| ID | Requirement | Why in this release ||---|---|---|| FR-1 | Save a note as a file without a network | the core of the product || NFR-1 | No note lost when the app is killed | the quality goal with the highest importance |
Out of scope: FR-2 → next release, FR-3 → next release.
Non-goals:
- No sync in this release.
## 3. Design
- Blueprint changes: §5 gets the note store container.- Interfaces and contracts: none- Data migrations: none
## 4. Alternatives considered
| Option | Why not | ADR ||---|---|---|| Save to a database | no direct file access for users | ADR-0002 |
## 5. Cross-cutting impact
| Concern | What changes | How it is checked ||---|---|---|| Privacy | notes stay on the device | no network call in the test run |
## 6. Acceptance and verification
| Criterion | Check to add first (red before green) | Evidence expected ||---|---|---|| AC-1 | `tests/test_save_kill.py` kills the app during 1 000 saves | test output |
## 7. Rollout and rollback
- Backup proved by restore: not applicable, no stored data before this release.- Window and who can roll back during it: any time; the owner can withdraw the package.
| Step | Action | How it is undone | Time to undo ||---|---|---|---|| 1 | publish the package to the test channel | withdraw the package | 10 minutes |
## 8. Work packages
| WP | Goal | Files | Done criterion | Estimate ||---|---|---|---|---|| WP-1 | note store saves and reads files | `app/store/` | AC-1 test passes | 2 agent-days || WP-2 | editor screen | `app/editor/` | a note is written and reopened by hand | 1.5 agent-days |
Total: 3.5 agent-days against an appetite of 4.
## 9. Risks and rabbit holes
| Risk or rabbit hole | Likelihood and impact | Mitigation ||---|---|---|| Android file permissions differ by version | medium, high | test on the three versions in the PRD |
Circuit breaker: when the appetite is reached, the lead stops and asks the owner; the default is to ship the store without the editor polish.
## 10. Open questions
| Question | Default | Who answers | By ||---|---|---|---|| Is the test channel private? | yes | owner | 2026-03-12 |Completion checks
A copy is complete when:
- every required field and section above is present, in the same order, and no bracketed placeholder is left;
- the template's comments are deleted from the copy;
- the owner has approved it, where the playbook asks for approval. Only the owner sets
approved.
Source
templates/release-spec.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.
---template: release-spec/1id: RS-NNN # RS-NNN or the release version (v1.2.0); never reusedtitle: Release spec — [release name]status: draft # draft | review | approved | released — the lead approves; the owner when scope or appetite changesversion: 0.1.0 # version of this release spec; a change of scope or appetite makes a new revisiontier: standard # lightweight | standard | high-assurance, as set at G0 (mgmt.governance-tiers)appetite: 3 agent-days # the time the owner will give this release; scope bends, time does notapprover: [lead; owner or client when the rules require it]prd: project/PRD.md@0.1.0 # the PRD version this release builds onblueprint: project/BLUEPRINT.md@0.1.0 # the Blueprint version this release builds ondate: YYYY-MM-DD---
# Release spec — [release name]
<!-- Template from the UASK Engineering Hub, item process.release-spec. Save as project/specs/RS-NNN.md (or beside the release plan). Write it before Build starts and get it approved at gate G2. Sections that need a tier say so in their first line; a section that does not apply says "none" and stays. Delete these comments when a section is written. -->
## 1. Context and scope
<!-- Why this release comes now, and what it builds on: the previous release, the pitch, the open findings. Two to five sentences. -->
## 2. Goals and non-goals
<!-- Goals are requirement ids from the PRD that this release delivers. Out of scope lists ids that are explicitly not delivered. Non-goals are things that could be goals but are not. -->
| ID | Requirement | Why in this release ||---|---|---|| FR-1 | … | … |
Out of scope: [ids, each with where it goes instead, for example "FR-n → next release"].
Non-goals:
- …
## 3. Design
<!-- Which sections of the Blueprint change, by number; which interfaces and contracts change; every data migration. A hard-to-reverse choice becomes an ADR, linked here. -->
- Blueprint changes: [§5 gets a new component …]- Interfaces and contracts: [none | list]- Data migrations: [none | list, with whether each can be reversed]
## 4. Alternatives considered
<!-- Required: standard, high-assurance --><!-- Options that were rejected, and why. Each hard-to-reverse choice is an ADR; name it in the last column. -->
| Option | Why not | ADR ||---|---|---|| … | … | — |
## 5. Cross-cutting impact
<!-- Required: standard, high-assurance --><!-- Only what this release changes: security, privacy, performance, accessibility, observability. -->
| Concern | What changes | How it is checked ||---|---|---|| Security | none | — |
## 6. Acceptance and verification
<!-- Each criterion has a method, an environment and an expected result (see the acceptance criteria item). Write the check first and see it fail before the code is written. Name the evidence the verifier will ask for. -->
| Criterion | Check to add first (red before green) | Evidence expected ||---|---|---|| AC-1 | … | test output, a screenshot, a log line |
## 7. Rollout and rollback
<!-- Write the rollback first. For a live system, name the backup that was proved by restore, and where it is kept (the backup rule of the project lifecycle item). Fill in the release checklist from this section. -->
- Backup proved by restore: [what, where, when, how restored]- Window and who can roll back during it: […]
| Step | Action | How it is undone | Time to undo ||---|---|---|---|| 1 | … | … | … |
## 8. Work packages
<!-- One package is the unit one builder takes: a goal, the files it touches, a Done criterion that someone else can check, an estimate. The total is compared with the appetite; if it is above, cut scope. -->
| WP | Goal | Files | Done criterion | Estimate ||---|---|---|---|---|| WP-1 | … | … | … | 0.5 agent-day |
Total: [n] against an appetite of [n].
## 9. Risks and rabbit holes
<!-- Required: standard, high-assurance --><!-- What could exceed the appetite, and the circuit breaker: when the appetite is reached with the work unfinished, the lead stops and puts the options and a default to the owner. -->
| Risk or rabbit hole | Likelihood and impact | Mitigation ||---|---|---|| … | … | … |
Circuit breaker: [when the appetite is reached, the lead stops and asks the owner; the default is …]
## 10. Open questions
<!-- Each question has a default that applies if nobody answers by the given date. -->
| Question | Default | Who answers | By ||---|---|---|---|| … | … | … | … |
## Close-out
<!-- Optional. Fill in when the release ships: link the release record and compare actual with appetite. -->
- Release record: […]- Actual effort against appetite: […]