Migration Playbook Generation Prompt for Platform Teams

Platform teams that treat prompts as production code need repeatable migration runbooks, not ad-hoc rollout notes. This prompt is designed for the release-preparation phase, specifically after compatibility checks and dry-run simulations have surfaced risks, but before the migration is handed off to SREs or operators. The ideal user is a platform engineer, release manager, or AI ops lead who has access to evidence from past instruction rollouts, incident reports, and team debriefs. The job-to-be-done is converting that raw operational history into a structured, step-by-step migration playbook that QA, SRE, and product teams can execute with clear checkpoints, rollback triggers, and communication templates.

To use this prompt effectively, you must provide concrete evidence as input: post-mortems from previous migrations, compatibility reports, dry-run simulation results, and a list of affected agent sessions or services. The prompt expects [EVIDENCE_DOCUMENTS] to be rich and specific; vague summaries will produce a vague playbook. The output is a structured plan with explicit phases, each containing a step description, the responsible team, a success checkpoint, a rollback trigger, and a communication template for stakeholders. For example, a checkpoint might be 'Verify that <5% of migrated sessions throw the new instruction compatibility error in the first 15 minutes,' and a rollback trigger might be 'If error rate exceeds 10% or P95 latency increases by >200ms, initiate rollback procedure R-01.' This level of operational detail is what separates a useful runbook from a generic checklist.

Do not use this prompt for initial instruction design, for writing the instructions themselves, or for real-time incident response. It is a planning tool, not an execution tool. If you are in the middle of an active incident, use the Instruction Rollback Trigger Prompt instead. If you haven't yet validated that the new instructions are compatible with your agent fleet, run the Instruction Compatibility Check Prompt first. The migration playbook is only as good as the evidence it synthesizes; if your team has no post-mortem culture or no dry-run data, the generated plan will contain speculative steps that should be flagged for human review before execution. Always pair the generated playbook with a human approval gate, especially for migrations affecting production customer-facing agents or regulated workflows.

This prompt template is designed to be pasted directly into your orchestration layer. It instructs the model to act as a platform reliability engineer and produce a detailed, step-by-step migration playbook. The playbook is built from a provided [PAST_ROLLOUT_LOG] and a [TARGET_MIGRATION_SCOPE], ensuring that the output is grounded in real operational history rather than generic best practices. The template uses square-bracket placeholders for all dynamic inputs, which your application must replace with real values before execution. The output is a structured Markdown document with explicit sections for pre-flight checks, execution steps, rollback triggers, and stakeholder communication.

markdownCopy
You are a senior platform reliability engineer. Your task is to generate a detailed, step-by-step migration playbook based on a past rollout log and a new target scope. The playbook must be actionable, include explicit checkpoints, and define clear rollback triggers.

## Input Data
- **Past Rollout Log:** [PAST_ROLLOUT_LOG]
- **Target Migration Scope:** [TARGET_MIGRATION_SCOPE]

## Playbook Structure and Constraints
Generate a Markdown document with the following sections. Adhere strictly to the constraints for each.

### 1. Executive Summary
- A 3-4 sentence summary of the migration, its criticality, and the primary lesson learned from the past rollout that is being applied here.

### 2. Pre-Flight Checks
- A checklist of 5-10 specific, verifiable conditions that must be true before starting.
- Each item must be a checkbox (`- [ ]`).
- Include checks for: deployment health, monitoring dashboard verification, on-call schedule confirmation, and a specific data integrity check derived from the [PAST_ROLLOUT_LOG].

### 3. Step-by-Step Execution Plan
- A numbered list of discrete, ordered actions.
- Each step must include:
    - **Action:** The precise command or operation to perform.
    - **Expected Outcome:** What success looks like.
    - **Checkpoint:** A specific metric or log line to verify before proceeding to the next step.
- The plan must incorporate a canary deployment or phased rollout strategy.

### 4. Rollback Triggers and Procedure
- Define 3-5 specific, observable conditions that will trigger an immediate rollback (e.g., error rate > X% for Y minutes, specific P1 alert fires).
- For each trigger, provide the exact rollback command or sequence of actions to execute.
- State the expected time to full rollback.

### 5. Communication Plan
- Draft a template for a "Migration Starting" notification.
- Draft a template for a "Migration Complete" notification.
- Draft a template for a "Migration Rolled Back" notification.
- Each template must have placeholders for `[STATUS_PAGE_LINK]` and `[INCIDENT_CHANNEL]`.

### 6. Lessons Learned Integration
- Explicitly list 2-3 specific failures or near-misses from the [PAST_ROLLOUT_LOG].
- For each, explain how this playbook's steps or checks are designed to prevent a recurrence.

## Output Rules
- Output only the valid Markdown document.
- Do not add any conversational preamble or postamble.
- If the [PAST_ROLLOUT_LOG] is empty or nonsensical, output a single line: "ERROR: Invalid past rollout log provided. Cannot generate playbook."

To adapt this template, replace the placeholders with your actual data. The [PAST_ROLLOUT_LOG] should be a structured summary of a previous, similar migration, including what went well and what failed. The [TARGET_MIGRATION_SCOPE] should clearly define the components, services, or infrastructure being changed in the new migration. Before deploying this prompt in a production pipeline, validate that the model reliably produces the ERROR: string when given empty or garbage input for [PAST_ROLLOUT_LOG]. This is a critical safety check to prevent the generation of a hallucinated playbook. For high-risk migrations, the generated playbook must be reviewed and approved by a human incident commander before any execution steps are initiated.

This prompt is designed to be called programmatically as part of a platform team's release workflow, not as a one-off chat interaction. The implementation harness should treat the prompt as a function that accepts structured inputs—previous migration logs, incident postmortems, and the target change description—and returns a validated playbook object. Because the output directly informs production changes, the harness must enforce schema validation, run pre-defined evaluation checks, and gate the result before any human operator sees it. The prompt is not a replacement for engineering judgment; it is a structured drafting tool that compresses scattered operational knowledge into a consistent, reviewable artifact.

Wire the prompt into a release pipeline or internal developer portal using a thin service wrapper. The service should accept a JSON payload with fields for [PREVIOUS_MIGRATION_LOGS], [INCIDENT_POSTMORTEMS], [TARGET_CHANGE_DESCRIPTION], [AFFECTED_SERVICES], and [RISK_TOLERANCE_LEVEL]. Before calling the model, the harness should validate that all required fields are present and that text fields meet minimum length thresholds to prevent low-quality outputs from sparse inputs. After receiving the model response, run a strict JSON schema validator against the expected playbook structure—sections for pre-flight checks, step-by-step migration steps, rollback triggers, communication templates, and lessons-learned integration must all be present and non-empty. If validation fails, retry once with the validation errors appended to the prompt as [CONSTRAINTS] feedback. If the second attempt also fails, log the failure, alert the release lead, and block the playbook from being published to the runbook system.

For model choice, prefer a model with strong instruction-following and long-context handling, such as Claude 3.5 Sonnet or GPT-4o, because the prompt must synthesize information from multiple long-form documents. Set temperature low (0.1–0.2) to prioritize consistency across runs. Log every generation with the input hash, model version, output schema validation result, and the human reviewer who approved the final playbook. In high-risk environments—such as database migrations, auth system changes, or payment pipeline updates—require explicit human approval before the playbook is loaded into the runbook automation system. The harness should also store the generated playbook alongside its source inputs and approval metadata for audit purposes, enabling post-migration reviews to trace decisions back to the evidence that informed them.

Common failure modes in the harness layer include: incomplete playbooks where the model omits rollback triggers due to ambiguous input, hallucinated service names when [AFFECTED_SERVICES] is not explicitly provided, and communication templates that lack specific stakeholder roles. Mitigate these by adding pre-generation input completeness checks and post-generation eval prompts that score the playbook on coverage of required sections, presence of concrete rollback criteria, and specificity of communication templates. If the eval score falls below a defined threshold, route the playbook for manual authoring instead of publishing it. Do not treat this prompt as a fire-and-forget generator; the harness is the safety boundary between a raw model output and a production migration order.