Module 05 / Lesson 03
Make the release call with a green, yellow, and red checklist
The AI will always tell you the code is ready. Only empirical verification and human judgment decide when to release.
It is Friday afternoon. The AI agent reports: "All changes implemented cleanly, ready for deployment!" But when a real visitor visits the live site, they receive stale cached information. Furthermore, a hidden security regression was introduced in an unreviewed helper function. Shipping without proof turns an AI shortcut into an outage.
Read the narration transcript
A ready-to-release change still needs a plan
The status app patch is ready for a release decision. The operator can publish. The public fixture shows the approved text, and the access checks pass.
I still need to know which version we'll release, who sees it first, and which evidence will make us stop. A green build is a useful input to that decision.
Treat each change according to its risk
Green work is easy to review and undo. Let the agent draft a skeleton, a small layout change, or a type, and run the usual checks.
Yellow work changes what people see or when they see it. Check caching, retries, error recovery, and new dependencies against real evidence.
Red work changes who can access data or whether we can recover it. A person approves permission changes, destructive migrations, and sensitive configuration before a release moves.
Stage the rollout and watch the real outcome
Start in staging. Publish a safe sample update and check the visitor sees it. Confirm the settings for the candidate version without copying secrets into a report.
If the evidence supports the next step, release to one approved pilot. Watch for successful saves that still produce stale public updates.
Any confirmed access problem stops the rollout. If successful saves stop reaching visitors, stop widening it and follow the agreed recovery plan.
Make a call and state why
Choose ship to the next group, hold for evidence, or stop a rollout already in progress. Say which observed result supports that call.
A code rollback may leave data to reconcile. Name the owner, then rerun the original smoke check after recovery. The final assessment gives you twelve decisions across this workflow to practice that judgment.
The everyday problem
You’ve reviewed the status app patch. The narrow publish change passes its local checks. You can show that operators publish and visitors get the expected update in a test. Now look at the release plan. It says push the button and then look at the dashboard. Who gets the change first? Which check do you run immediately? What would make you stop?
This is where responsibility becomes visible. An agent can help write a checklist, summarize test evidence, or draft a rollout note. The people operating the service choose the release criteria and are accountable for monitoring. Before launch, identify who will make the stop decision and how that person can recover the service.
Why the agent got it wrong
Builds, tests, and scans answer useful pre-release questions. They do not tell you whether the released version reached the intended environment, whether an environment setting differed, or whether users can see a real new update. A smoke check is a small test of an essential behavior immediately after deployment.
Some changes make recovery harder than reverting a commit. A data migration could leave records that an older application version cannot read. A notification may already have reached its recipient. Mark those effects in the plan. The most useful release decision depends on the change’s actual risk, not a general label applied to every CRUD operation.
The tool and technique
Use a release plan with a version, scope, evidence, owner, and stop signal. First review the changes that control access or mutate data. Choose a limited initial audience when you have a supported way to do that. In the status app the candidate release reaches one synthetic or approved pilot organization first under the product’s existing rollout mechanism.
Ask the agent for a release note that separates confirmed checks and open work. Give it the exact records you want referenced, such as the operator publish test, the public visitor result, the migration history reviewed with sample data, and the human approval for access rules. Ask it to identify the first missing decision rather than filling it in.
Sort changes by risk and set a release gate
Green changes such as layout and types can start with agent drafts and routine checks. Yellow changes such as caching, dependencies, and webhook retries need review plus test evidence. Red changes such as permissions, production secrets, and destructive migrations need approval from the person accountable for the release.
pnpm lint && pnpm typecheck && pnpm test pnpm exec playwright test semgrep scan --config ./semgrep.yml --metrics=off --error pnpm build Watch: Approved update visible after refresh. Stop: An approved update disappears or an access check fails. Owner: Named release operator with a known rollback version.
Record the commands that actually run in the project, who signed off on the high-risk change, and the evidence that would trigger a rollback. If any of those facts is missing, the scenario’s answer can be to hold.
On screen in the status app
The first note below declares the release ready because the build passed. The revised note identifies the version and the pilot, checks that a published update reaches the public page, and requires a stop if a successful publish starts to appear stale for visitors. Adjust the exact stop signal to what the team can measure. Keep source examples synthetic or approved.
In the walkthrough, follow the new version into staging. Confirm required settings are present without printing their values. Execute the smoke check against designated test data. Inspect success and failure metrics and a public freshness signal. Before widening exposure, decide which result to wait for and who will review it. Separate illustrative report values from numbers the team actually observed.
docs/delivery-release-note.md
Before
The build passed. Roll out everywhere. Watch the dashboard.
After
Candidate: the reviewed commit with the publish change. First audience: one approved pilot organization. Smoke check: publish sample text and confirm the public view shows it. Stop if successful saves stop reaching the public view or any confirmed access boundary fails. Owner: release lead coordinates recovery and any data reconciliation.
What to watch for
An isolated smoke test can pass while real usage shows problems. Monitor signals that represent the user outcome and keep an alert action simple enough to follow. If the audience is small, volume-based thresholds may be noisy. A single confirmed violation of a critical data access rule can be enough to stop. Coordinate with the organization owner instead of relying on traffic percentages alone.
Plan recovery for both application and data. If rolling back code cannot undo a published change, define who reconciles the affected state. Keep the earlier version or rollback procedure available, and rehearse a recovery in a safe environment when feasible. An agent may draft the plan, while a human approves the actions.
How you know it worked
Read the staged results and make the call. Would you release to the pilot, hold for a missing check, or stop a rollout already in progress? Cite the specific evidence behind the answer. Say what the team should do next and which observation would change the decision. Run the same public smoke check after a recovery if one is needed.
The final assessment gives you a set of the status app decisions from the brief through release. Carry the same habit into each one: name what the evidence proves, name the gap, and choose the next action that will close it.