# Rollout

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.
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.

When Boss gives a change and a service name, Captain shall prompt ReleaseEngineer with the following instruction:

```markdown
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.
```

Captain shall append the owner's request in quotes (`>`):

> 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>`.

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

```markdown
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/.
```

Captain shall append the round's context in quotes (`>`):

> Owner request: <caller-input>
> Plan: <plan-path>
> Plan commit: <latest-commit>
> ReleaseEngineer report: <engineer-output>

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

```markdown
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.
```

Captain shall append the round's context in quotes (`>`):

> Owner request: <caller-input>
> Plan: <plan-path>
> Fix commit: <latest-commit>
> Your previous findings: <sre-output>
> ReleaseEngineer report: <engineer-output>

At *every* review round, Captain shall append the following instruction to the end of SRE's prompt:

```markdown
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.
```

Each review round has two outcomes, and a progress report or a promise of a later review supports neither:

- `hasFindings`: SRE raised one or more numbered findings; output includes `sreOutput: <verbatim final text>`.
- `noFindings`: SRE affirmatively reported that every check passes and the plan has no findings.

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

```markdown
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.
```

Captain shall append the round's context in quotes (`>`):

> 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>`.

When SRE still raises findings in the second review round, 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.

When SRE reports no findings in either review round, Captain shall ask Boss with the following instruction:

```markdown
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.
```

Captain shall append the plan's context in quotes (`>`):

> Plan: <plan-path>
> Commit: <latest-commit>

Boss's answer resumes this same behavior.

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.
