Write the ship/no-ship memo

1512. Lesson identity

Module

4.1 — Release engineering

Lesson

Write the ship/no-ship memo

Academic type

Integration

Schema type

Practical

Order

3 of the module

Estimated time

45–60 minutes

This lesson integrates release gates, evidence review, immutable revision tracking, risk disposition, and decision communication. You will produce a short memo for one specific candidate build.

1513. Learning objective

After this lesson, you can write a ship/no-ship memo that identifies a candidate through an immutable anchor, compares it with the last known-good checkpoint, separates blockers, accepted risks, and missing evidence, applies previously defined thresholds, and records who authorized any accepted risk.

1514. Why this matters

A release gate records what must be checked; a ship/no-ship memo records the decision reached from those checks. The memo prevents a vague statement such as “looks ready” from becoming an undocumented release decision.

The decision must be tied to the exact candidate that was evaluated. A branch or ordinary tag can move, so its name alone may not identify the evaluated content. Prefer a full commit SHA or an artifact identifier that is mapped to that SHA. Branch and tag names are useful context unless the release process demonstrably guarantees that they are immutable.

The memo must also distinguish three different conditions:

• Blocker: a threshold is failed or a required condition prevents release.
• Accepted risk: a known issue or limitation is allowed under an existing policy or by an identified approving authority after its impact and evidence are reviewed.
• Missing evidence: a required check is unrun or inconclusive, so the gate cannot yet support shipping.

An accepted risk is not a disguised pass. A required gate cannot be waived merely by rewriting or lowering its threshold after reviewing the evidence. If an exception is permitted, the memo must cite the authority or defined policy that permits it.

1515. Prior knowledge

You should already be able to:

• identify the candidate revision and scope of a release check;
• define evidence, an owner, and a readiness condition for a gate;
• distinguish a failed check from an unrun or inconclusive check;
• use the release gate fields from Build a release gate in module 4.1.

1516. Core concept

A defensible release decision is a thresholded claim about a named candidate, not a general impression about the project.

A useful memo answers seven questions:

1. Which build is being considered, and what immutable revision or artifact anchor identifies it?
2. What last known-good checkpoint is the comparison baseline?
3. What changed since that baseline, and which checks were rerun because of those changes?
4. Which thresholds apply, and what evidence supports each result?
5. What is blocked, failed, unrun, or inconclusive?
6. Which known risks, if any, are accepted, by whom, under what authority or policy, and with what follow-up condition?
7. What decision follows, and what evidence or correction would cause reconsideration?

If you select Hold pending evidence, record it as a no-ship state. The candidate must not ship until the required evidence is obtained and the decision is reconsidered.

1517. Mental model: the Decision Ledger

The reasoning chain is:

immutable candidate → baseline and changed scope → existing thresholds → evidence states → blockers or accepted risks → decision → reconsideration condition

Do not change a required threshold simply because the candidate does not meet it. Changing a gate is a separate governance decision and cannot retroactively convert missing or failed evidence into a pass.

1518. Worked example

Assume candidate build CB-07 is artifact artifact-CB-07, mapped in the build record to full commit SHA 8f31c2a4e6b7d941ac78157b24575a199cd99310. Its branch, recorded only as context, is release/cb-07. The last known-good checkpoint is 6a20b19d67001bd062a30b599728dc38ce6654f4.

The release gate requires:

• completion of the core playthrough without a blocking defect;
• successful launch from a clean target environment;
• recorded evidence for every required check.

Baseline comparison

Since the last known-good checkpoint, the candidate changes the startup configuration and replaces presentation assets in one menu. Because startup behavior changed, the clean-environment launch check must be rerun. Because the menu assets changed, the relevant menu presentation and navigation checks must also be rerun. The unchanged core path was rerun as a regression check and completed twice.

Available results:

• core path: verified, two recorded runs against the candidate SHA;
• clean-environment launch: not run;
• menu navigation: verified;
• menu alignment issue: verified known issue, limited to one label and owned by the interface maintainer.

The menu issue could be proposed as an accepted risk only if the memo states its user impact, cites the supporting evidence, names its owner, identifies the approving authority or policy, and defines a follow-up condition. Calling it “non-blocking” without that disposition is insufficient.

Even if the menu issue is properly accepted, the clean-environment check remains required and unrun. Its threshold cannot be waived by relabeling it after this evidence review.

A defensible conclusion is:

Decision: No-ship for artifact-CB-07 at this time. The artifact maps to commit 8f31c2a4e6b7d941ac78157b24575a199cd99310. Compared with baseline 6a20b19d67001bd062a30b599728dc38ce6654f4, startup configuration and menu assets changed. Core-path and menu-navigation checks were rerun and passed, but the required clean-environment launch check was not run. The menu alignment issue may be considered separately as an accepted risk only through the documented authority or policy. The missing launch evidence keeps this candidate in a no-ship state. Reconsider after the clean-environment result is recorded against the same commit, or create a new decision record if the candidate changes.

This conclusion does not predict that the candidate will fail. It states that the required evidence is absent.

1519. AI-native workflow

Use AI to organize supplied records and challenge unsupported claims, not to make the release decision.

1. Gather the candidate artifact record, full commit SHA, contextual branch or tag, baseline, changed scope, gate definitions, test notes, unresolved issues, and relevant risk policy.
2. Ask AI to sort only the supplied material into verified, failed, not run, inconclusive, and candidate accepted risk.
3. Check every classification against the source records. Remove unsupported inferences.
4. For each proposed accepted risk, require impact, evidence, owner, approving authority or policy, and follow-up condition.
5. Write the threshold application and final decision yourself.
6. Ask AI to identify any sentence that lacks an evidence source, candidate anchor, threshold, or authorization basis.

AI cannot turn an unrun check into evidence, authorize a risk, or decide that a required threshold no longer applies.

1520. Git and artifact workflow

1. Record the candidate build identifier.
2. Record a full commit SHA or an artifact identifier mapped to that SHA.
3. Record branch or tag names only as context unless your documented process guarantees their immutability.
4. Record an immutable last known-good revision or controlled checkpoint.
5. Identify the changed scope between baseline and candidate.
6. Confirm that each evidence item belongs to the candidate anchor.
7. If the candidate changes, create a new decision record rather than reusing the old decision.

1521. Guided practice

Write a 150–250 word ship/no-ship memo for CB-07 or for a candidate you are authorized to evaluate.

Release decision memo
Candidate build or artifact:
Full commit SHA mapped to the candidate:
Branch or tag context:
Last known-good checkpoint:
Changed scope since baseline:
Checks rerun because of those changes:
Decision: Ship / No-ship / Hold pending evidence (no-ship until reconsidered)
Scope:
Required thresholds:
Verified evidence:
Failed, unrun, or inconclusive evidence:
Blockers:
Accepted risks and rationale:
- Risk and impact:
- Supporting evidence:
- Owner:
- Approving authority or defined policy:
- Follow-up condition:
Reasoning:
Condition for reconsidering the decision:
Owner and next action:

Complete the exercise in six passes:

1. Anchor the candidate. Use a full commit SHA or an artifact identifier mapped to it. Add a branch or tag only as context.
2. Compare with the baseline. State what changed and which checks were rerun because of those changes.
3. Apply existing thresholds. Do not soften or rewrite a required threshold after reviewing the evidence.
4. Classify evidence. Keep verified, failed, not run, and inconclusive results distinct.
5. Dispose of known risks. For every accepted risk, document impact, evidence, owner, authority or policy, and follow-up condition. If these are absent, do not label the risk accepted.
6. Record the decision. Explain which threshold controls it and what would permit reconsideration.

1522. Validation / evidence

Your memo is complete when it contains:

• one unambiguous candidate build or artifact identifier;
• a full commit SHA or artifact-to-SHA mapping;
• branch or tag names treated only as context unless their immutability is documented;
• an immutable last known-good checkpoint;
• a meaningful comparison of changed scope;
• the checks rerun because of those changes;
• at least two explicit, previously defined release thresholds;
• separate verified, failed, not-run, and inconclusive evidence states;
• blockers identified without disguising missing evidence as a pass;
• an Accepted risks and rationale section, even if it states “None”;
• for every accepted risk: impact, supporting evidence, owner, approving authority or defined policy, and follow-up condition;
• confirmation that a required gate was not waived merely by changing its threshold after evidence review;
• a decision recorded against the exact candidate anchor;
• if using “Hold pending evidence,” an explicit no-ship status until reconsideration;
• a concrete condition for reconsideration and a next owner or action.

Another developer should be able to determine exactly what was evaluated, what changed, which checks were rerun, what remains blocked or unknown, which risks were formally accepted, who authorized them, and what would reopen the decision.

1523. Key takeaways

• Anchor the decision to a full commit SHA or an artifact mapped to it.
• Compare changed scope and relevant rerun checks with the last known-good checkpoint.
• Keep blockers, accepted risks, and missing evidence distinct.
• An accepted risk requires impact, evidence, ownership, authority or policy, and follow-up.
• A required gate cannot be waived by rewriting its threshold after reviewing evidence.
• “Hold pending evidence” remains no-ship until the decision is reconsidered.

1524. Knowledge check

1525. Next lesson

This decision record closes the release-engineering sequence. Continue to 4.2 — Live ops, beginning with Live ops is an operating model, where you will distinguish live operations from ordinary post-release maintenance.

1526. Knowledge check