# Rollout

## Intent

Roles:

- ReleaseEngineer
- SRE

Boss, the change owner, supplies as one input a change — a commit on the current branch — and the name of the service it deploys.
`<caller-input>` is that complete input as Boss gave it, retained unchanged for every prompt that relays the owner request.
The rollout plan is one Markdown file under docs/rollouts/; every plan commit lands on the current branch, and no existing commit is rewritten.
No one in this playbook deploys: the repository's deploy script runs only in dry-run mode.
Captain shall use the repository-effect receipt as the authoritative identity of every plan commit.
At most two SRE review rounds run: the first reviews the plan commit, the second reviews ReleaseEngineer's fix commit.

## External Behavior

### ROLLOUT-1

The plan commit's identity is the one the repository-effect receipt reports.
Where ReleaseEngineer asks the owner a question, Boss's answer resumes this same behavior.

When Boss gives a change and a service name, Captain shall prompt ReleaseEngineer:

> Write a canary rollout plan for the change and the service in the owner's request below.
> First confirm that the change is a commit on the current branch, that the service has deploy manifests under deploy/, and that the repository has a deploy script with a dry-run mode; if any of these is not so, ask the owner one question and wait for the answer.
> Read specs/ and the service's deploy manifests under deploy/.
> Write the plan as one Markdown file under docs/rollouts/, named after the service and the change's short commit hash.
> List the canary stages in order, each with its traffic percentage and its duration.
> For each stage, list the health signals to watch, each with its threshold stated as a number with its unit, using only signals the service actually emits.
> For each stage, give the exact command that rolls that stage back.
> Dry-run the first stage with the repository's deploy script in its dry-run mode, and record the exact command and its complete output in the plan; if the dry run fails, record the failure as it is.
> Never run the deploy script outside dry-run mode, and never change any live environment.
> Commit the plan in one commit on the current branch; never rewrite an existing commit.
> Report the plan path, the commit hash, and whether the dry run succeeded.
>
> > Owner request: <caller-input>

Results:
- `planned`: ReleaseEngineer committed the plan in one commit on the current branch. Output shall include `latestCommit: <commit identity>`, `planPath: <repository path of the plan file>`, and `engineerOutput: <verbatim final text>`.

### ROLLOUT-2

The first review round reviews the plan commit, whose identity is the one the repository-effect receipt reports.

When ReleaseEngineer commits the plan, at the first review round, Captain shall prompt SRE:

> A review begins for the rollout plan committed for the change and the service below.
> Read the plan commit, the plan file, specs/, and the service's code and deploy manifests under deploy/.
>
> Check that every stage has a rollback command.
> Check that every health signal is one the service actually emits, as its code, metrics configuration, or deploy manifests show.
> Check that every threshold is stated as a number.
> Check that the recorded dry run of the first stage succeeded; you may repeat it with the deploy script in dry-run mode, never outside it.
> Raise a finding for every place a check fails, and only for failed checks — not for wording or style.
> Number your findings, and for each name the stage and the signal or command it concerns.
> If every check passes, say plainly that the plan has no findings.
> Do not edit files or commit; report findings only.
>
> > Owner request: <caller-input>
> > Plan: <plan-path>
> > Plan commit: <latest-commit>
> > ReleaseEngineer report: <engineer-output>

Results:
- `hasFindings`: SRE raised one or more numbered findings; a progress report or a promise of a later review supports neither review outcome. Output shall include `sreOutput: <verbatim final text>`.
- `noFindings`: SRE affirmatively reported that every check passes and the plan has no findings; a progress report or a promise of a later review supports neither review outcome.

### ROLLOUT-3

The fix commit lands on the current branch, its identity is the one the repository-effect receipt reports, and no existing commit is rewritten.
Where ReleaseEngineer asks the owner a question, Boss's answer resumes this same behavior.

When SRE raises findings in the first review round, Captain shall prompt ReleaseEngineer:

> Fix every numbered SRE finding below in the rollout plan.
> If a fix changes the first stage, or the recorded dry run failed, dry-run the first stage again with the deploy script in dry-run mode, and record the new command and its complete output in the plan.
> Never run the deploy script outside dry-run mode, and never change any live environment.
> If a finding cannot be fixed from what the repository shows, ask the owner one question and wait for the answer.
> Commit the fixes in one new commit on the current branch; never rewrite an existing commit.
> Report, by finding number, what you changed, and the new commit hash.
>
> > Owner request: <caller-input>
> > Plan: <plan-path>
> > SRE findings: <sre-output>

Results:
- `fixed`: ReleaseEngineer committed the fixes in one new commit on the current branch. Output shall include `latestCommit: <commit identity>` and `engineerOutput: <verbatim final text>`.

### ROLLOUT-4

The second review round reviews ReleaseEngineer's fix commit, whose identity is the one the repository-effect receipt reports; no further review round runs after it.

When ReleaseEngineer commits fixes after the first review round, at the second and last review round, Captain shall prompt SRE:

> A second review round begins for the rollout plan below, with particular attention to the fix commit.
> Read the fix commit and the whole plan as it now stands, and check that each of your previous findings is resolved.
>
> Check that every stage has a rollback command.
> Check that every health signal is one the service actually emits, as its code, metrics configuration, or deploy manifests show.
> Check that every threshold is stated as a number.
> Check that the recorded dry run of the first stage succeeded; you may repeat it with the deploy script in dry-run mode, never outside it.
> Raise a finding for every place a check fails, and only for failed checks — not for wording or style.
> Number your findings, and for each name the stage and the signal or command it concerns.
> If every check passes, say plainly that the plan has no findings.
> Do not edit files or commit; report findings only.
>
> > Owner request: <caller-input>
> > Plan: <plan-path>
> > Fix commit: <latest-commit>
> > Your previous findings: <sre-output>
> > ReleaseEngineer report: <engineer-output>

Results:
- `hasFindings`: SRE still raised one or more numbered findings; a progress report or a promise of a later review supports neither review outcome. Output shall include `sreOutput: <verbatim final text>`. On this outcome the review limit is reached: Boss is not asked, and the playbook ends reporting the plan as not cleared for rollout, returning the latest commit hash, the plan path, and SRE's unresolved numbered findings.
- `noFindings`: SRE affirmatively reported that every check passes and the plan has no findings; a progress report or a promise of a later review supports neither review outcome.

### ROLLOUT-5

Boss's answer resumes this same behavior.

When SRE reports no findings in either review round, Captain shall ask Boss:

> Tell the owner that the rollout plan below has passed SRE review, then ask exactly one question: "Start the rollout with this plan?"
> Wait for the owner's answer; if it is neither a yes nor a no, ask the same question again.
>
> > Plan: <plan-path>
> > Commit: <latest-commit>

Results:
- `approved`: Boss answered yes. On this outcome the playbook ends reporting the plan as approved for rollout, returning the latest commit hash and the plan path.
- `rejected`: Boss answered no. On this outcome the playbook ends reporting the plan as rejected, returning the plan path and Boss's reason as given in the answer.
