Context Preservation Across Model Upgrades Prompt

This prompt is designed for teams that are upgrading the underlying model powering an agent while that agent holds active, saved state. The core job-to-be-done is to produce a compatibility report that identifies state elements likely to behave differently under the new model and a migration plan with fallback checkpoints. The ideal user is an engineering lead or AI operator who has a serialized agent state snapshot, the old model identifier, the new model identifier, and a description of the agent's task and tool contracts. Use this before you switch the model endpoint on a running agent to avoid silent behavioral regressions that corrupt in-flight execution.

Do not use this prompt for fresh agents with no saved state, for simple single-turn prompts, or as a substitute for regression testing your prompt templates against the new model. The prompt assumes you have a complete state snapshot, not a partial log or a human-readable summary. If your agent state includes tool call histories, plan progress, and unresolved dependencies, this prompt will analyze each element for compatibility risks such as tool schema mismatches, reasoning fidelity changes, or instruction-following drift. The output should feed directly into your upgrade gating decision: proceed, proceed with mitigations, or rollback and retry with adjusted state.

Before running this prompt, confirm that you have a validated state snapshot and that both model identifiers are accurate. After receiving the compatibility report, use the migration plan's fallback checkpoints to structure a staged rollout. If the report flags high-risk state elements, pair this prompt with a regression test suite that replays the flagged state against the new model in a sandboxed environment before production cutover. Never rely on this prompt alone for safety-critical agent workflows; always include human review for state migrations that involve financial transactions, healthcare data, or irreversible side effects.

This prompt template is designed to be pasted directly into your orchestration layer. It instructs the model to analyze a serialized agent state produced by a previous model version, identify elements that may behave differently under a new target model, and produce a structured compatibility report with a concrete migration plan. The output includes fallback checkpoints, behavioral regression flags, and safe upgrade gating criteria. Replace every square-bracket placeholder with live data before calling the model.

textCopy
You are an AI migration analyst. Your task is to evaluate whether an agent's saved state, originally produced by [SOURCE_MODEL_IDENTIFIER], will transfer safely to [TARGET_MODEL_IDENTIFIER].

## INPUT

### Agent State Snapshot
[AGENT_STATE_JSON]

### Source Model Behavior Notes
[SOURCE_MODEL_BEHAVIOR_NOTES]

### Target Model Capability Profile
[TARGET_MODEL_CAPABILITY_PROFILE]

### Upgrade Constraints
[UPGRADE_CONSTRAINTS]

## OUTPUT SCHEMA

Return a single JSON object with the following structure:

{
  "compatibility_assessment": {
    "overall_risk": "LOW" | "MEDIUM" | "HIGH" | "BLOCKED",
    "risk_summary": "string explaining the primary risk factors",
    "state_elements_analyzed": ["list of state element paths examined"]
  },
  "regression_flags": [
    {
      "state_element": "path.to.field",
      "expected_behavior_change": "string describing how the target model may interpret or act on this element differently",
      "severity": "CRITICAL" | "HIGH" | "MEDIUM" | "LOW",
      "evidence": "string citing specific capability differences or known behavioral shifts"
    }
  ],
  "migration_plan": {
    "recommended_action": "PROCEED" | "PROCEED_WITH_FALLBACKS" | "HOLD" | "REQUIRES_REPLAY",
    "pre_upgrade_steps": ["ordered list of actions to take before switching models"],
    "fallback_checkpoints": [
      {
        "checkpoint_id": "string",
        "state_element_path": "path.to.snapshot",
        "rollback_condition": "string describing when to revert to this checkpoint",
        "expected_behavior": "string describing safe behavior under the source model"
      }
    ],
    "post_upgrade_validation": ["ordered list of checks to run after migration"]
  },
  "safe_upgrade_gate": {
    "criteria": ["list of conditions that must be true to proceed"],
    "blocking_conditions": ["list of conditions that must be false to proceed"],
    "human_approval_required": true | false,
    "approval_context": "string summarizing what a human reviewer must confirm"
  }
}

## CONSTRAINTS

- Do not assume the target model will interpret tool call histories, plan steps, or reasoning traces identically to the source model.
- Flag any state element that relies on source-model-specific output formatting, instruction-following quirks, or tool schema assumptions.
- If the agent state contains partially completed multi-step reasoning, assess whether the target model will continue coherently or diverge.
- For any CRITICAL severity regression flag, require human approval before migration.
- If the overall risk is BLOCKED, the migration plan must specify a full replay strategy instead of a state transfer.
- Base all assessments on the provided capability profiles and behavior notes. Do not speculate about model internals.

## EXAMPLES

[FEW_SHOT_EXAMPLES]

## RISK LEVEL

[RISK_LEVEL]

Adaptation guidance: Replace [AGENT_STATE_JSON] with the full serialized state from your checkpoint system. [SOURCE_MODEL_BEHAVIOR_NOTES] should include known quirks, output patterns, and instruction-following characteristics of the current model. [TARGET_MODEL_CAPABILITY_PROFILE] should describe the new model's tool-use behavior, reasoning style, and known differences from the source model. [UPGRADE_CONSTRAINTS] should specify any hard requirements such as maximum acceptable regression risk, required human approval gates, or prohibited state modifications. [FEW_SHOT_EXAMPLES] should contain 1-3 example state elements with their expected behavioral changes to calibrate the model's regression detection sensitivity. [RISK_LEVEL] should be set to HIGH if the agent operates on production infrastructure, customer data, or irreversible actions; set to LOW for internal development agents where rollback is cheap.

Before deploying this prompt in a production migration pipeline, validate the output against a golden dataset of known state transfer failures. Common failure modes include the model under-flagging subtle instruction-following differences, over-flagging benign format variations, and producing migration plans that assume tool availability not yet provisioned for the target model. Run this prompt against at least three representative agent states with known behavioral regressions and confirm that CRITICAL flags are raised before any automated migration proceeds. For high-risk domains, always route the safe_upgrade_gate output to a human reviewer and log the full compatibility report alongside the migration decision for auditability.

The Context Preservation Across Model Upgrades prompt is not a one-off analysis tool—it is a gating step in a model upgrade pipeline. Wire it between the saved state store and the new model's execution environment. The prompt consumes a serialized agent state blob (plan, completed steps, tool outputs, pending decisions) and a model capability diff (what changed in tool calling, reasoning, output formats, or refusal behavior). It produces a structured compatibility report and a migration plan. This report should be treated as a machine-readable artifact, not a human-only summary, so downstream automation can act on it.

Implement the harness as a pre-upgrade validation service. On receiving a state blob and a model version identifier, the service loads the relevant model capability diff from a registry, renders the prompt with both inputs, and calls the target model. Parse the output against a strict JSON schema that includes compatibility_score, breaking_changes[], behavioral_risks[], migration_steps[], and fallback_checkpoint_id. If compatibility_score falls below a configurable threshold (e.g., 0.7) or breaking_changes is non-empty, block the upgrade and route to a human review queue. Log the full prompt, response, and parsed report for audit. For high-risk domains, require explicit human approval before any migration step is applied to production state.

After approval, the migration steps become a runbook. Each step should reference a specific state key, the expected transformation, and a validation check. Execute these steps in a sandboxed replay environment first, then run the Resume-from-Checkpoint Validation Prompt against the migrated state to confirm integrity. If validation fails, roll back to the fallback_checkpoint_id and escalate. Wire the entire flow into your CI/CD pipeline for model upgrades: state export → compatibility check → human gate → migration → validation → production cutover. Never auto-migrate state without a validated fallback checkpoint.