Build reusable prompt templates with variables, versioning, and change control
Create an owned prompt registry that safely references OpenAI reusable prompts from the Responses API, validates typed variables, pins platform versions, proves consumer compatibility, evaluates candidates, and supports controlled promotion and complete rollback.
Replace copied or mutable production prompts with reproducible application releases that map a logical task to an exact prompt ID/version, model and contracts, and that cannot change traffic without review, evidence and a tested rollback target.
- OpenAI Responses API current
- OpenAI reusable prompts versioned
- Node.js 22 LTS or current supported LTS
- OpenAI project access An approved project provides separate roles for prompt authoring and production release control, with API keys kept on trusted backends.
Confirm project, editor, reviewer and deployer identities without exposing credentials. - Prompt inventory All current prompt call sites, consumers, owners, contracts, models and production selectors are known.
Run the registry audit and reconcile runtime prompt IDs. - Machine-readable contracts Variable and response schemas express allowed names, types, bounds, trust classes and compatibility versions.
Run contract fixtures for every consumer. - Evaluation and reviewers Candidate/control datasets, graders and subject-matter annotations cover normal, boundary, adversarial and consequential behavior.
Confirm dataset and grader release IDs plus human agreement. - Reversible deployment Runtime can select an immutable release, report effective prompt/model versions, perform shadow/canary rollout and atomically restore the previous bundle.
Run non-production promotion and rollback smoke.
OneLiners never runs these steps or stores secrets. Review placeholders, versions, current state, and change-control requirements before using a command.
Full guide
What you will build
- A governed prompt-template registry that gives every reusable task an owner, immutable application release, OpenAI prompt ID and pinned prompt version, typed variable contract, supported model set, evaluation dataset, rollout state, deprecation date and previous known-good version.
- A safe renderer and request adapter for OpenAI reusable prompts in the Responses API. It validates variable names, types, sizes and sensitivity before interpolation; keeps trusted instructions separate from untrusted values; references an explicit prompt ID and version; and records the effective release without exposing secrets.
- A prompt change-control workflow with reviewed diffs, annotated evaluation evidence, candidate-versus-control testing, compatibility checks for variables and consumers, shadow and canary rollout, atomic promotion, rollback rehearsal and retirement of unsupported versions.
- Application code refers to a stable logical prompt name and an immutable release manifest. The manifest pins the OpenAI prompt object/version, model policy, variable contract, response contract, validator revision and evaluation release used for every request.
- Missing, extra, mistyped, oversized or secret-bearing variables fail before a model call. Untrusted values cannot alter developer policy, escape their serialized data boundary, select another prompt version or introduce an unapproved tool.
- A prompt author can publish a candidate in the OpenAI dashboard without silently changing production. Deployment requires a reviewed registry change and evaluation evidence; consumers remain pinned until the release pointer is deliberately promoted.
- Operators can reproduce and roll back a bad release even when prompt text, examples, model choice and schemas evolved together. The prior OpenAI prompt version and matching local contracts stay available through the rollback window.
Architecture
How the parts fit together
The team separates authoring identity from deployment identity. OpenAI stores reusable prompt objects and their versions; the application registry maps a logical task to an exact prompt ID/version plus local contracts and release evidence. A typed variable validator minimizes and serializes values before the Responses API request references that prompt. A server-side adapter selects only approved releases and records the effective prompt/model metadata. CI verifies registry syntax, variable compatibility, rendered boundaries, fixtures and candidate/control evals. A deployment controller moves a small cohort to a candidate and can atomically restore the previous manifest. Prompt caching is treated as an optimization of exact stable prefixes, not a correctness mechanism, and cache metrics cannot override release quality.
- Inventory repeated model tasks and assign one logical prompt, owner, consumer set, risk level and retirement policy to each narrowly defined behavior.
- Define a typed variable contract and sensitivity classification before authoring text; reject secrets and free-form policy overrides.
- Author the reusable prompt with stable instructions first, clearly labelled variables, explicit data boundaries, response rules and aligned examples.
- Publish a candidate prompt version in the OpenAI dashboard, record its prompt ID/version in a candidate registry entry and leave production pinned.
- Validate every consumer and fixture against the candidate variable/output contracts, then compare candidate and control with the same model settings and graders.
- Review the prompt, example, contract, model and operational diff as one release; deploy first in shadow and then to a bounded canary.
- Promote the immutable manifest after the observation window, retain the prior release and continuously mine reviewed failures into the next evaluation version.
Assumptions
- The application uses the OpenAI Responses API for reusable prompt references; the implementation does not assume that the same prompt-object feature exists in Chat Completions.
- Prompt creation and editing occur through approved OpenAI project access, while production deployment additionally requires a reviewed change to the application's registry or release pointer.
- Every prompt consumer can report its expected variable and response-contract version in CI and production telemetry.
- The backend protects the API key and release configuration, validates variables before the request and prevents model output from authorizing or executing consequential actions.
- The team can retain prior prompt versions and local release artifacts through a defined rollback and audit window.
- Evaluation cases and annotations are representative, redacted, reviewed by subject-matter experts and kept separate from prompt-authoring examples and production secrets.
Key concepts
- Logical prompt
- The stable application-facing task name, such as support-triage. It resolves to a release manifest rather than directly to mutable prompt text.
- OpenAI prompt ID and version
- The platform identifier and optional pinned version used by the Responses API prompt parameter. Omitting a version can select a moving default, so controlled production releases pin one.
- Variable contract
- The versioned list of allowed variable names, types, lengths, sensitivity classes and serialization rules shared by prompt authors and consumers.
- Application release
- An immutable manifest that joins prompt ID/version, model, variable and response schemas, renderer, validators, dataset, graders and rollout evidence.
- Breaking prompt change
- A revision that removes or renames a variable, changes its meaning or trust boundary, alters the response contract, expands authority, changes tool expectations or invalidates a consumer.
- Prompt drift
- Unreviewed behavior change caused by a moving prompt version, model alias, example, context assembler or consumer contract rather than an explicit atomic release.
- Version rollback
- Restoring the previous complete manifest and explicit OpenAI prompt version, followed by smoke verification and telemetry confirmation.
Before you copy
Values used in this guide
{{logicalPrompt}}Stable task name used by application code.
Example: support-triage{{openaiPromptId}}Reusable prompt identifier copied from the approved OpenAI project.
Example: pmpt_abc123{{openaiPromptVersion}}Exact platform prompt version pinned for this release.
Example: 17{{templateRelease}}Immutable application release joining platform and local contracts.
Example: support-triage/3.2.0{{model}}Model approved for the release by evaluation.
Example: gpt-5.6{{evalDataset}}Reviewed fixture set used by candidate and control.
Example: evals/support-triage-v12.jsonl{{canaryPercent}}Bounded production cohort for the candidate release.
Example: 5{{customerMessage}}Example untrusted variable validated and serialized as user data.
Example: My replacement order has not moved for 48 hours.Security and production boundaries
- Do not pass API keys, passwords, session cookies, private keys or unrestricted personal data as reusable prompt variables. Secret management and authorization belong outside the prompt.
- A prompt ID is not a secret or authorization token, but production access to edit prompt objects and change the release registry is privileged and must be auditable.
- Treat every runtime variable as untrusted. Validate and serialize values, preserve tenant boundaries and keep them out of developer instructions even if their names sound administrative.
- Never let a variable choose the developer message, prompt ID/version, model, tool list, tenant, approval status or safety policy.
- Prompt and model output cannot enforce access control or approve state changes. Use application allowlists, typed proposals and human/change-policy gates.
- Minimize telemetry: record version IDs, statuses, validator outcomes, tokens and latency; retain raw variables or responses only under the approved data policy.
Stop before continuing if
- Stop if a candidate variable contract is incompatible with any production consumer and no coordinated migration or compatibility adapter exists.
- Do not deploy when the registry omits an explicit prompt version, model policy, validator revision, dataset release or previous rollback target.
- Stop if prompt authors can change the production-selected version without the application's normal review and deployment controls.
- Do not accept variables that contain secrets, bypass tenant authorization, select tools or inject application policy.
- Block promotion on any critical eval regression, unhandled refusal/incomplete state, validation bypass, latency/cost breach or missing rollback rehearsal.
- Rollback when runtime telemetry reports a prompt/model release different from the approved manifest or when prior-version reproduction fails.
instruction
Inventory narrow reusable tasks and owners
List every repeated model task, its consumers, authority, evidence, output contract, risk, current template location and owner. Merge only truly compatible tasks and split templates whose policy or decision boundary differs.
Why this step matters
A template library becomes unsafe when it is organized around convenient wording rather than product contracts. Inventory tasks and consumers before creating a reusable prompt. Two screens that both summarize text may have different evidence, privacy and escalation rules; one template with conditionals can let a low-risk consumer inherit high-impact authority. Conversely, copied templates drift and hide duplicated maintenance. Record one logical task per compatible contract, a named owner, supported consumers, risk and current release. The audit should flag missing ownership, mixed authority and likely duplicates for human review. Do not auto-merge based on text similarity: prompt behavior depends on context assembly, schemas, models and downstream use.
What to understand
Map every call site to a logical prompt and expected variable/output contract.
Separate prompt ownership from consumer ownership and production deployment authority.
Classify consequential decisions independently from surface task names.
Keep deprecated or unknown templates visible until consumers are proven migrated.
System changes
- Creates the authoritative prompt and consumer inventory without changing runtime selection.
Syntax explained
--require-owner- Fails the audit when a logical prompt lacks a named owner.
--report-consumers- Lists each call site so compatibility and migration can be verified.
prompts/registry.yamlprompts:
support-triage:
owner: support-ai
risk: caution
consumers: [agent-console, intake-api]
authority: recommend_queue_only
release: support-triage/3.2.0
refund-decision:
owner: payments-policy
risk: danger
consumers: [refund-review]
authority: human_review_requirednode prompt-registry/audit.mjs prompts/registry.yaml --require-owner --report-consumerslogical_prompts: 7 owned: 7 consumer_links: 14 missing_contracts: 0 mixed_authority_candidates: 1 duplicate_task_candidates: 2 registry_audit: needs_review
Checkpoint: Every runtime prompt maps to one owned logical task
node prompt-registry/audit.mjs prompts/registry.yaml --require-owner --report-consumersContinue whenAll prompts and consumers are identified; mixed authority and duplicates have explicit review decisions.
Stop whenA production call site or consequential authority cannot be mapped to an owner and contract.
If this step fails
A hidden legacy template appears during deployment.
Likely causeThe inventory searched only one repository or SDK wrapper.
Search call sites, environment configuration and dashboard references.Compare API telemetry prompt IDs with registry entries.
ResolutionAdd the consumer and block migration until its contract and owner are known.
Security notes
- Do not merge prompts across tenants, authority levels or data classes to reduce template count.
Alternatives
- Keep a task local to one service when reuse would create coupling without operational benefit.
Stop conditions
- A production call site or consequential authority cannot be mapped to an owner and contract.
config
Define the immutable template release manifest
Create a release record that binds the logical prompt to an explicit OpenAI prompt ID/version, approved model, variable and response schemas, renderer, validator, eval dataset, owners, change record and rollback target.
Why this step matters
Prompt text is only one behavior dependency. A rollback that restores words but leaves a new model, variable serializer or response validator cannot reproduce the old system. Define an immutable application release manifest that joins all relevant components. Use your own semantic release identifier for communication and change policy while retaining the exact OpenAI prompt version used by the Responses API. Hash local artifacts or identify immutable builds, link eval and approval evidence, and name a rollback target. The manifest should not contain API keys, customer data or full prompt content; it is a deployment bill of materials. CI validates completeness, and runtime telemetry emits its release ID.
What to understand
Never use a mutable latest label as the only production prompt reference.
Include model and all contracts because compatibility depends on the complete request and response path.
Keep application release numbers distinct from platform prompt-version numbers and record their mapping.
Require one known-good rollback target whose dependencies still exist.
System changes
- Adds an immutable candidate release record but does not change the current production pointer.
Syntax explained
openai_prompt.id/version- Pins the platform reusable prompt object and exact reviewed version.
renderer_sha256- Identifies the local variable serialization and role assembly implementation.
rollback_target- Names the complete previous application release, not merely a prompt text revision.
releases/support-triage/3.2.0.json{
"logical_prompt": "support-triage",
"release": "support-triage/3.2.0",
"openai_prompt": {"id":"pmpt_abc123","version":"17"},
"model": "gpt-5.6",
"variable_contract": "support-triage-vars/4.1",
"response_contract": "support-triage-output/3.0",
"renderer_sha256": "675fb9...",
"validator_sha256": "c416e2...",
"eval_dataset": "support-triage-v12",
"rollback_target": "support-triage/3.1.4"
}Values stay on this page and are never sent or saved.
node prompt-registry/validate-release.mjs releases/{{templateRelease}}.jsonlogical_prompt: support-triage release: support-triage/3.2.0 openai_prompt: pmpt_abc123@17 model_policy: gpt-5.6 variable_contract: 4.1 response_contract: 3.0 rollback_target: support-triage/3.1.4 manifest_status: valid
Checkpoint: The candidate is reproducible as one atomic release
node prompt-registry/validate-release.mjs releases/{{templateRelease}}.jsonContinue whenExplicit prompt ID/version, model, contracts, artifact identities, eval evidence and rollback target.
Stop whenAny runtime dependency is mutable, absent or cannot be restored from the manifest.
If this step fails
Two manifests reference the same release name with different hashes.
Likely causeRelease artifacts were edited after publication.
Compare repository history and artifact store digests.Inspect deployment provenance.
ResolutionRevoke the ambiguous release and create a new immutable version after review.
Security notes
- Keep credentials and customer data out of release manifests; restrict who may change the current pointer.
Alternatives
- Use a signed deployment artifact containing the same fields when a separate registry file does not fit the platform.
Stop conditions
- Any runtime dependency is mutable, absent or cannot be restored from the manifest.
config
Define typed variables, bounds, and sensitivity
Specify every allowed variable's type, maximum size, required status, trust class and serialization method. Reject unknown fields, secrets and policy selectors before rendering or calling the API.
Why this step matters
Variables are an interface, not convenient string substitutions. Define which values callers may supply and how each crosses the trust boundary. Free-form text is untrusted even when an internal service produced it. Enums can be application-trusted only after authorization and validation. Set size limits to prevent accidental context explosion and denial of service. Reject extra fields so a consumer cannot smuggle a policy override or secret through a harmless-looking template. Use separate application channels for model selection, authorization and tools; never expose them as variables. A secret scanner is useful defense in depth but cannot classify all sensitive data, so the contract and data flow must prohibit it deliberately.
What to understand
Version variable meaning, not just spelling; changing a field from plain text to trusted policy is breaking.
Serialize arrays and objects structurally rather than joining them with ambiguous delimiters.
Normalize encoding and validate lengths after decoding so alternate representations cannot bypass bounds.
Report validation errors without echoing sensitive input into logs or user-visible traces.
System changes
- Creates the variable schema enforced by all prompt consumers.
Syntax explained
additionalProperties=false- Fails closed when a caller sends an undeclared variable.
x-trust- Application metadata documenting how the renderer must serialize and label a field.
maxLength- Bounds context and abuse risk before a model request is created.
schemas/support-triage-vars.schema.json{
"type": "object",
"required": ["customer_message", "channel", "locale"],
"properties": {
"customer_message": {"type":"string","maxLength":12000,"x-trust":"untrusted"},
"channel": {"enum":["email","chat","web"],"x-trust":"trusted-enum"},
"locale": {"enum":["en-US","en-GB","pl-PL"],"x-trust":"trusted-enum"}
},
"additionalProperties": false
}node prompt-registry/check-variables.mjs schemas/support-triage-vars.schema.json fixtures/triage-input.jsonrequired: 3/3
unknown_fields: 0
size_violations: 0
secret_patterns: 0
trust_classes: {untrusted_text: 1, trusted_enum: 2}
variable_contract: passCheckpoint: Only declared, bounded, non-secret values can render
node prompt-registry/check-variables.mjs schemas/support-triage-vars.schema.json fixtures/triage-input.jsonContinue whenRequired fields present, no unknown or oversized values, no secret patterns and explicit trust classes.
Stop whenA variable selects policy, prompt version, model, tools, tenant or authorization, or may contain a secret.
If this step fails
A valid consumer starts failing after a prompt update.
Likely causeThe candidate added or changed a required variable without a coordinated contract version.
Compare variable schemas and consumer reports.Inspect release compatibility classification.
ResolutionRestore compatibility or ship a versioned migration; never silently fill a consequential value.
Security notes
- Do not rely on variable names such as safe or admin; trust follows validated provenance and authorization.
Alternatives
- Derive trusted enums server-side from authenticated state rather than accepting them from callers.
Stop conditions
- A variable selects policy, prompt version, model, tools, tenant or authorization, or may contain a secret.
config
Author stable instructions and explicit data slots
Write direct developer instructions, response rules and aligned examples in the reusable prompt. Place stable content first, dynamic variables in labelled user data, and define missing/conflicting-data behavior without asking for hidden reasoning.
Why this step matters
Reusable prompts reward stable, clear structure. Put durable task and safety rules in the developer message, use direct instructions and specific success criteria, and place validated variables in labelled user data. Static-first ordering can also improve exact-prefix caching on eligible requests, but semantic authority comes first. State that free-form customer content is untrusted and cannot change policy. Define what to do when required data is missing or ambiguous. Few-shot examples must obey the same contracts and should exist because evals demonstrate a benefit. A redacted renderer preview lets reviewers inspect roles, variable placement and stable prefix without copying sensitive values or making a model call.
What to understand
Keep prompt policy independent of any one customer, locale or incident.
Use structural serialization so variable content cannot close a delimiter and append developer text.
Ask for observable output and evidence, not private chain-of-thought.
Recalculate the stable prefix identity whenever instructions, schemas or examples change.
System changes
- Defines candidate reusable prompt content and changes the rendered model input when selected.
Syntax explained
--redact- Shows roles, slot names, sizes and hashes without printing raw variable values.
stable_prefix_sha256- Identifies stable rendered content for review and cache analysis, not for security authorization.
user_data_blocks- Confirms untrusted variables remain in a lower-authority labelled data section.
Values stay on this page and are never sent or saved.
node prompt-registry/render-preview.mjs releases/{{templateRelease}}.json fixtures/triage-input.json --redactrelease: support-triage/3.2.0 developer_blocks: 1 user_data_blocks: 1 variables_rendered: [customer_message, channel, locale] untrusted_delimited: true stable_prefix_sha256: 442ab3... preview_status: valid
Checkpoint: The rendered template preserves role and trust boundaries
node prompt-registry/render-preview.mjs releases/{{templateRelease}}.json fixtures/triage-input.json --redactContinue whenStable developer content, exactly declared variables, delimited untrusted text and no raw secret output.
Stop whenA runtime value enters developer instructions, examples contradict policy, or review requires revealing sensitive content.
If this step fails
The customer message appears as a new instruction block.
Likely causeRaw interpolation or template escaping failed.
Inspect the role-aware serialized request.Replay delimiter and Unicode boundary fixtures.
ResolutionUse structured content serialization and add a regression before publishing the prompt version.
Security notes
- Prompt delimiters help interpretation but do not replace external authorization, tool allowlists or output validation.
Alternatives
- Use typed tool input or file content blocks when they provide a safer structure for complex data.
Stop conditions
- A runtime value enters developer instructions, examples contradict policy, or review requires revealing sensitive content.
instruction
Publish a candidate OpenAI prompt version without selecting it
In the approved OpenAI project, create or update the reusable prompt, publish a new version, record its prompt ID and exact version in the candidate manifest, and leave the production registry pointer unchanged.
Why this step matters
OpenAI reusable prompts allow authoring and versioning in the dashboard and referencing a prompt ID, optional version and variables through the Responses API. Publishing a platform version is not the same as deploying it. Record the exact ID/version in a candidate application manifest and keep the production pointer pinned to its current release. Restrict dashboard edit access, document the source change and reviewer, and never treat an unversioned visual preview as release evidence. The verification tool should read only prompt metadata or compare an exported approved snapshot according to your platform controls; it must not print secret variables. If the platform cannot expose the metadata required by your process, require a manual attestation plus rendered/eval evidence rather than guessing.
What to understand
Use the correct OpenAI project and access role; prompt IDs from another project may be unavailable or inappropriate.
Capture prompt ID, exact version, author, review record and publication time in the application change record.
Do not change the current release pointer during authoring.
Treat version publication as candidate creation followed by normal compatibility, eval and rollout gates.
System changes
- Creates a new reusable prompt version in the approved OpenAI project and maps it to a non-production candidate manifest.
Syntax explained
--prompt- Specifies the reusable platform prompt object.
--version- Selects the exact immutable platform version under review.
selected_by_production=false- Proves authoring did not move the application release pointer.
Values stay on this page and are never sent or saved.
node prompt-registry/verify-platform-reference.mjs --prompt {{openaiPromptId}} --version {{openaiPromptVersion}} --release {{templateRelease}}prompt_id: pmpt_abc123 prompt_version: 17 project: production-ai release_mapping: support-triage/3.2.0 selected_by_production: false reference_status: verified_candidate
Checkpoint: The candidate exists and production remains pinned
node prompt-registry/verify-platform-reference.mjs --prompt {{openaiPromptId}} --version {{openaiPromptVersion}} --release {{templateRelease}}Continue whenCandidate ID/version resolves in the approved project, maps to the manifest and is not current production.
Stop whenThe prompt belongs to the wrong project, the version is unknown/mutable, or publishing it changes production selection.
If this step fails
The prompt reference cannot be resolved.
Likely causeProject access, ID/version mapping or platform configuration is wrong.
Verify project and prompt metadata without exposing API keys.Compare the application manifest with the reviewed dashboard object.
ResolutionCorrect the candidate mapping; never fall back to an unpinned latest version.
Security notes
- Limit prompt editing and production selection permissions separately and audit both.
Alternatives
- Keep the candidate in repository-managed templates when platform reusable prompts are unavailable, with equivalent version and release controls.
Stop conditions
- The prompt belongs to the wrong project, the version is unknown/mutable, or publishing it changes production selection.
config
Call the pinned prompt through the Responses API
From the trusted backend, pass the exact prompt ID, explicit version and validated variables in the Responses API request. Pin the approved model policy in the release and record effective metadata, status and usage.
Why this step matters
The runtime adapter is where version governance becomes real. Load an immutable approved release, validate variables locally, and send the prompt object with both ID and explicit version through the Responses API. The current API reference describes prompt as a template reference with variables; verify its exact SDK shape for the installed version. Keep the API key on the backend. Attach only non-sensitive release metadata and record request ID, response status, usage and downstream validator result. Do not let callers override prompt ID, version or model. When a variable is missing or invalid, fail before the API call rather than interpolating null, an invented default or a secret from environment state.
What to understand
Load releases from an allowlisted registry, not a user-supplied path or prompt ID.
Validate and minimize variables before constructing the API request.
Handle completed, refusal, incomplete and API error states before parsing expected output.
Keep SDK and API reference verification in the dependency-update checklist.
System changes
- Adds the billable backend request path for explicitly versioned reusable prompts.
Syntax explained
prompt.id- Identifies the approved reusable prompt object from the release manifest.
prompt.version- Pins the evaluated platform version and prevents silent drift.
prompt.variables- Supplies only values that passed the versioned local variable contract.
src/ai/run-reusable-prompt.mjsimport OpenAI from "openai";
import { loadRelease, validateVariables } from "./prompt-registry.js";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
export async function runPrompt(releaseName, rawVariables) {
const release = loadRelease(releaseName);
const variables = validateVariables(release.variableContract, rawVariables);
return client.responses.create({
model: release.model,
prompt: {
id: release.openaiPrompt.id,
version: release.openaiPrompt.version,
variables
},
metadata: { release_id: release.release }
});
}Values stay on this page and are never sent or saved.
node prompt-registry/smoke.mjs --release {{templateRelease}} --fixture fixtures/triage-input.jsonrelease: support-triage/3.2.0 prompt: pmpt_abc123@17 model: gpt-5.6 variables_valid: true response_status: completed output_contract: pass request_id_recorded: true
Checkpoint: Runtime uses exactly the approved prompt release
node prompt-registry/smoke.mjs --release {{templateRelease}} --fixture fixtures/triage-input.jsonContinue whenExpected ID/version/model, valid variables, handled response status, passing output contract and request trace.
Stop whenCallers can override release fields, version is omitted, key is client-visible, or invalid variables reach the API.
If this step fails
The API accepts the request but output uses an older contract.
Likely causeThe manifest maps the wrong prompt version or runtime loaded stale release configuration.
Compare effective prompt metadata and manifest digest.Restart or invalidate the application release cache safely.
ResolutionStop traffic to the candidate and restore the correctly mapped immutable release.
Security notes
- Never expose API keys or permit arbitrary prompt IDs and variables from a client.
Alternatives
- Render a repository-managed prompt server-side when platform prompt objects do not meet required release controls.
Stop conditions
- Callers can override release fields, version is omitted, key is client-visible, or invalid variables reach the API.
verification
Check every consumer for breaking changes
Compare candidate and current variable/output contracts, then run each registered consumer's fixtures. Classify additions, removals, renames, semantic changes, authority changes and output-shape changes before evaluation.
Why this step matters
A reusable prompt is a shared interface. Even a quality improvement can break a consumer that omits a new variable, expects a legacy status or interprets a field differently. Compare contracts before expensive evals and run fixtures for every registered call site. Syntax compatibility is insufficient: changing the meaning of priority or expanding from recommendation to approval is breaking even if the JSON type remains string. Classify optional and required additions, removals, renames, bounds, trust classes, response shapes and authority. Require an explicit migration for breaking changes and keep old and new releases concurrently available until consumers report the expected version.
What to understand
Generate compatibility from machine-readable contracts and supplement it with owner review of semantic/authority changes.
Run consumer-specific fixtures with the candidate renderer and validator.
Require each runtime consumer to emit its expected contract version.
Do not use default values to conceal missing policy or authorization information.
System changes
- Produces a compatibility report and may block release; it does not modify consumers.
Syntax explained
--from/--to- Select exact release manifests for an interpretable interface diff.
--all-consumers- Runs every registered call-site fixture rather than one happy path.
authority_expansion- Flags behavioral privilege changes independently from syntax.
Values stay on this page and are never sent or saved.
node prompt-registry/compat.mjs --from support-triage/3.1.4 --to {{templateRelease}} --all-consumersconsumers_checked: 2 variable_changes: added_optional: [locale] removed: [] renamed: [] output_breaks: 0 authority_expansion: false fixture_pass: 42/42 compatibility: backward_compatible
Checkpoint: Every consumer can safely use or migrate to the candidate
node prompt-registry/compat.mjs --from support-triage/3.1.4 --to {{templateRelease}} --all-consumersContinue whenNo undeclared break, all fixtures pass and any migration has owner, sequencing and rollback.
Stop whenA consumer is missing, authority expands, or a breaking contract change lacks coordinated migration.
If this step fails
Compatibility reports pass while a consumer parses the wrong status.
Likely causeThe machine-readable response schema did not capture semantic meaning.
Review status vocabulary with each consumer owner.Add semantic fixtures and typed exhaustiveness checks.
ResolutionMark the change breaking and migrate consumers explicitly.
Security notes
- Treat authority and trust-class changes as security changes even when schemas remain valid.
Alternatives
- Create a new logical prompt when contracts cannot remain compatible without ambiguous branching.
Stop conditions
- A consumer is missing, authority expands, or a breaking contract change lacks coordinated migration.
verification
Evaluate the candidate with reviewed annotations
Run candidate and control on the same frozen dataset and settings. Use deterministic checks, precise graders and subject-matter annotations, then record per-consumer, per-risk and operational metrics in the release evidence.
Why this step matters
Version numbers prove identity, not quality. Evaluate the candidate against the deployed control with identical inputs, model policy, context and graders. OpenAI's evaluation guidance emphasizes task-specific datasets, automation where suitable and human calibration; its prompt optimizer documentation likewise depends on annotations, critiques and graders that precisely express desired properties. Use deterministic interface and policy checks first, then semantic graders and blinded domain labels. Inspect per-consumer and high-risk strata. Keep optimizer suggestions as candidates: they may be useful starting points but require review and the same release process. Record model, prompt versions, dataset and grader revisions with the result.
What to understand
Use annotations that explain the failure, not only a thumbs-up/down label.
Keep a holdout separate from examples and frequent optimization iterations.
Block on unsupported commitments, privacy leaks or authorization mistakes regardless of average score.
Measure latency and tokens because template and example growth affects production budgets.
System changes
- Creates billable evaluation runs and immutable candidate evidence; does not select production.
Syntax explained
--control/--candidate- Runs exact release manifests so prompt and model differences are visible.
human_annotation_agreement- Shows whether automated graders remain aligned with reviewed intent.
unsupported_commitments- Critical safety/business-policy release blocker.
Values stay on this page and are never sent or saved.
node prompt-registry/eval.mjs --dataset {{evalDataset}} --control support-triage/3.1.4 --candidate {{templateRelease}}dataset: support-triage-v12 rows: 210 consumer_contract_pass: 210/210 policy_accuracy: 0.952 vs 0.943 unsupported_commitments: 0 vs 0 human_annotation_agreement: 0.88 p95_latency_ms: 1320 vs 1290 release_gate: pass_for_shadow
Checkpoint: The candidate is better or equivalent on every required boundary
node prompt-registry/eval.mjs --dataset {{evalDataset}} --control support-triage/3.1.4 --candidate {{templateRelease}}Continue whenAll compatibility and critical gates pass, quality meets per-stratum targets, graders are calibrated and budgets are acceptable.
Stop whenCandidate/control settings differ, holdout regresses, critical output occurs or grader agreement is insufficient.
If this step fails
Optimizer output scores well but violates an ungraded policy.
Likely causeThe dataset or graders omit a material constraint.
Review candidate changes against the task contract.Label policy-boundary fixtures with domain owners.
ResolutionReject the candidate, add the missing grader/case and repeat the full comparison.
Security notes
- Never auto-publish optimizer output; it is model-generated content requiring review and evaluation.
Alternatives
- Edit manually when the proposed optimization obscures intent or cannot be explained by failure evidence.
Stop conditions
- Candidate/control settings differ, holdout regresses, critical output occurs or grader agreement is insufficient.
decision
Review the full prompt release diff and change record
Review prompt messages, variables, examples, model, schemas, validators, data handling, eval evidence, operational budgets, migration and rollback together. Require security or policy owners for authority and sensitive-data changes.
Why this step matters
Prompt changes can alter behavior without changing application code, so review must cover the full release. Show a readable diff of developer instructions and examples, a machine-readable contract diff, selected model/settings, data-handling implications, validator and grader changes, eval evidence, consumer migration, rollout plan and rollback rehearsal. Require specialist approval when authority, security, privacy, regulated policy or consequential actions change. The reviewer should understand why each change exists and which failure or requirement it addresses. A large generated rewrite without a traceable reason is harder to validate and rollback than a focused revision.
What to understand
Separate wording-only changes from contract, authority and data-flow changes.
Link each material edit to an eval failure, policy decision or supported feature change.
Prevent the prompt author from being the only production approver for high-impact releases.
Record approvals and rejected alternatives without embedding customer data in the change record.
System changes
- Creates approval evidence and can authorize rollout; no traffic changes until deployment executes.
Syntax explained
--from/--to- Builds the review pack from exact immutable releases.
--verify-signoffs- Fails when required owner, security, privacy or policy approvals are missing.
data_handling_diff- Makes retention, new variables and sensitive fields part of release review.
Values stay on this page and are never sent or saved.
node prompt-registry/review-pack.mjs --from support-triage/3.1.4 --to {{templateRelease}} --verify-signoffsprompt_diff: reviewed variable_diff: backward_compatible response_diff: none model_diff: none data_handling_diff: none eval_evidence: attached security_signoff: not_required owner_signoff: approved change_record: complete
Checkpoint: Reviewers approved the behavior and operational change
node prompt-registry/review-pack.mjs --from support-triage/3.1.4 --to {{templateRelease}} --verify-signoffsContinue whenComplete focused diff, linked evidence, required approvals, compatible consumers and tested rollback plan.
Stop whenA material change lacks rationale/eval evidence or the required independent owner has not approved.
If this step fails
The review pack shows a large unexplained rewrite.
Likely causeOptimization or copying replaced focused change control.
Map edits to failing cases and contract changes.Compare a minimal candidate.
ResolutionReduce the change or split it into independently evaluable releases.
Security notes
- Authority, tool, tenant and sensitive-data changes require security review even when presented as prompt wording.
Alternatives
- Keep the candidate in draft and collect more failure evidence before requesting approval.
Stop conditions
- A material change lacks rationale/eval evidence or the required independent owner has not approved.
decision
Shadow and canary the exact template release
Run the candidate silently, then route an approved stable cohort to the complete candidate manifest. Compare by release and consumer, keep consequential actions behind existing approvals, and arm automatic stop rules.
Why this step matters
The canary must use the same immutable manifest evaluated and approved. Shadow mode first detects integration and distribution failures without changing user-visible output. Canary assignment should be stable and bounded by consumer, tenant and risk. Compare candidate with control using validator results, outcome labels, complaints, refusals, latency, tokens and prompt/model metadata. Keep all existing human and application approvals; a new prompt cannot expand write authority during an experiment. Define stop thresholds and observation time before starting, and make routing independent of untrusted variable content.
What to understand
Verify the effective OpenAI prompt version in canary telemetry, not only the logical release label.
Compare variable and intent distributions between candidate and control.
Prevent shadow responses from writing data or being displayed as authoritative.
Automatically set candidate traffic to zero on critical contract, privacy or policy failure.
System changes
- Routes the approved cohort to the candidate release while retaining the control.
Syntax explained
--require-shadow- Blocks user-visible canary traffic until silent integration evidence passes.
--percent- Bounds exposure but does not override consumer/risk eligibility.
write_authority_changed=false- Confirms the experiment does not expand downstream privileges.
Values stay on this page and are never sent or saved.
node prompt-registry/deploy.mjs canary --release {{templateRelease}} --percent {{canaryPercent}} --require-shadowrelease: support-triage/3.2.0 prompt: pmpt_abc123@17 shadow: passed canary_percent: 5 consumers: [agent-console, intake-api] automatic_stop_rules: armed write_authority_changed: false deployment: canary_active
Checkpoint: Canary runtime matches the approved candidate
node prompt-registry/deploy.mjs status --release {{templateRelease}} --effective-versionsContinue whenExact prompt/model/contracts, bounded comparable cohort, active stop rules and unchanged approvals.
Stop whenRuntime version differs, cohort is unbounded, write authority expands, or a critical stop rule fires.
If this step fails
A canary host still uses the control prompt version.
Likely causeRelease caches or configuration propagation are inconsistent.
Inspect effective release metadata per host.Compare registry and deployment revisions.
ResolutionPause routing, converge immutable configuration and restart the observation window.
Security notes
- Canary size does not make unauthorized actions safe; retain all hard policy gates.
Alternatives
- Stay in shadow mode for high-impact tasks until sufficient reviewed evidence exists.
Stop conditions
- Runtime version differs, cohort is unbounded, write authority expands, or a critical stop rule fires.
verification
Promote, monitor, and prove version rollback
After the observation window, atomically move the logical prompt pointer to the candidate manifest. Keep the previous OpenAI prompt version and matching contracts deployable, monitor drift, and rehearse restoring the complete prior release.
Why this step matters
Promotion changes one logical pointer only after every gate passes. The prior release remains intact with its exact OpenAI prompt version, model, variable/output contracts and validators. Test rollback before promotion and again after any platform or dependency migration. Monitoring should report effective release IDs, validation failures, refusal/incomplete rates, outcome metrics, latency, tokens and consumer compatibility. A prompt version may be retired only after every consumer migrates and the audit/rollback window closes. If a regression occurs, restore the previous atomic manifest first, verify smoke and only then analyze or create a new candidate; editing the failing version in place destroys evidence.
What to understand
Promote by immutable pointer or signed configuration, never by overwriting prior artifacts.
Keep prompt platform and application release mappings queryable for incident response.
Run critical smoke and consumer contract checks immediately after the pointer changes.
Define deprecation and deletion separately; a non-current version may still be required for audit or rollback.
System changes
- Selects the candidate for all eligible production traffic and preserves the prior complete release.
Syntax explained
promote- Moves the application logical prompt pointer after release approval.
--verify-rollback- Proves the exact previous release remains callable and compatible.
effective_prompt- Confirms runtime OpenAI prompt ID/version matches the promoted manifest.
Values stay on this page and are never sent or saved.
node prompt-registry/deploy.mjs promote --release {{templateRelease}} --verify-rollback support-triage/3.1.4logical_prompt: support-triage new_current: support-triage/3.2.0 effective_prompt: pmpt_abc123@17 previous: support-triage/3.1.4 rollback_smoke: passed monitoring: armed promotion: complete
Checkpoint: Current and previous template versions are operational
node prompt-registry/deploy.mjs status --logical {{logicalPrompt}} --include-previous; node prompt-registry/smoke.mjs --release {{templateRelease}} --fixture fixtures/triage-input.jsonContinue whenCurrent and rollback manifests resolve, effective version is correct, smoke passes and monitoring is release-aware.
Stop whenPrevious version or matching contracts are unavailable, runtime identity differs, smoke fails or alerts are missing.
If this step fails
Selecting the previous version does not restore behavior.
Likely causeThe rollback changed only the platform prompt version while local model, schema, renderer or validator stayed new.
Compare complete manifests and runtime hashes.Run consumer fixtures against the restored release.
ResolutionRestore the full prior application release atomically and verify before reopening traffic.
Security notes
- Restrict and audit promotion/rollback authority; do not permit a prompt author alone to bypass required release approval.
Alternatives
- Keep the candidate at the last safe canary percentage when full promotion lacks evidence but rollback is not required.
Stop conditions
- Previous version or matching contracts are unavailable, runtime identity differs, smoke fails or alerts are missing.
Finish line
Verification checklist
node prompt-registry/validate-release.mjs releases/{{templateRelease}}.jsonExplicit OpenAI prompt ID/version, model, contracts, artifacts, eval dataset, owners and rollback target.node prompt-registry/compat.mjs --from support-triage/3.1.4 --to {{templateRelease}} --all-consumersNo undeclared breaking or authority change and every consumer fixture passes.node prompt-registry/eval.mjs --dataset {{evalDataset}} --control support-triage/3.1.4 --candidate {{templateRelease}}Critical gates, per-consumer quality, human calibration, latency and cost thresholds pass.node prompt-registry/deploy.mjs verify --logical {{logicalPrompt}} --current {{templateRelease}} --rollback support-triage/3.1.4Runtime resolves the exact current and previous platform prompt versions and both pass smoke.Recovery guidance
Common problems and safe checks
The API says a prompt variable is missing.
Likely causeThe application contract and selected platform prompt version disagree, or a consumer omitted a newly required variable.
Compare the registry variable schema with the exact pinned prompt version.Run compatibility checks for every consumer.
ResolutionRestore the compatible version or deploy a coordinated consumer/schema migration; do not insert an invented default.
An extra variable appears to be ignored.
Likely causeThe validator allows unknown keys or a renamed variable remains in one consumer.
Reject additional properties before the API call.Inspect consumer contract reports.
ResolutionFail closed on unknown variables and remove or migrate the stale producer.
Production behavior changes without an application deployment.
Likely causeThe request omitted the prompt version or resolved a mutable latest/default platform revision.
Inspect effective prompt metadata in requests.Compare runtime with the release manifest.
ResolutionPin the reviewed version and require a new application release for every production selection change.
A variable changes developer policy.
Likely causeUntrusted content is interpolated into the instruction block or raw template syntax allows boundary escape.
Render the request with an injection fixture.Inspect roles and serialized content boundaries.
ResolutionMove the variable into labelled user data, use structural serialization and keep authorization outside the model.
A prompt edit improves one consumer and breaks another.
Likely causeMultiple incompatible tasks share one logical template or the evaluation set omits a consumer.
Report metrics and contracts by consumer.Diff evidence, output and authority requirements.
ResolutionFork the prompt or add a coordinated versioned interface rather than hidden conditional behavior.
The candidate cannot be reproduced from the dashboard.
Likely causeThe release recorded only a prompt ID, not version, model, schemas and local renderer state.
Inspect the complete release manifest.Compare platform version and local artifact hashes.
ResolutionCreate an immutable manifest and rerun evals; screenshots are not deployable evidence.
Prompt caching shows few cache hits.
Likely causeDynamic content appears before stable instructions, prefixes differ, or traffic is too fragmented.
Compare rendered prefixes and cached token metrics.Check whether optimization is worth its complexity.
ResolutionPlace stable content first and variables later where semantically correct; never change correctness boundaries merely for cache rate.
A dashboard candidate was accidentally made current.
Likely causeAuthoring and production selection permissions or procedures are coupled.
Inspect platform audit history and application registry.Confirm production requests remain pinned.
ResolutionRestore the previous explicit version, separate authoring from deployment approval and alert on manifest mismatch.
Candidate evals pass but canary validators fail.
Likely causeThe eval renderer, variable distribution or selected version differs from production.
Compare request manifests and variable strata.Replay minimized failing inputs against both paths.
ResolutionStop the canary, align renderers and add the failure to the frozen set before a new release.
Rollback text is correct but output schema errors continue.
Likely causeThe prior prompt was restored without its matching response schema or validator.
Diff atomic release manifests.Run the previous consumer compatibility matrix.
ResolutionRestore prompt, model, variable/output contracts and validators as one release.
A variable containing personal data appears in normal logs.
Likely causeTelemetry logs rendered variables rather than redacted identifiers and measurements.
Inspect logging fields and retention.Search protected logs under incident procedure without copying data.
ResolutionStop the leak, restrict access, follow incident policy and replace raw values with approved redacted telemetry.
The prompt optimizer proposes a fluent but unsafe revision.
Likely causeOptimization rewards incomplete graders or treats generated text as automatically deployable.
Run safety and high-severity holdout cases.Inspect which annotations and graders drove the change.
ResolutionKeep the proposal as a candidate, improve reviewed graders and require owner approval plus normal release gates.
Reference
Frequently asked questions
Why not let production always use the newest prompt version?
Because a mutable version creates unreviewed behavioral change and makes incidents hard to reproduce. Pin the evaluated version and promote deliberately.
Are reusable prompts available through Chat Completions?
OpenAI documents reusable prompt references for the Responses API and notes they are not available in Chat Completions. Verify the current API reference before implementation.
Should secrets be template variables?
No. Retrieve secrets only in the authorized application component that needs them. Models and prompt templates should receive the minimum non-secret facts required for the task.
Can the prompt optimizer publish automatically?
Treat optimizer output as an untrusted candidate. OpenAI recommends review because optimized prompts can have mistakes; run normal eval, safety, change-control and rollout gates.
Recovery
Rollback
Restore the previous complete application release, including its exact OpenAI prompt ID/version, model, variables, response schema, renderer and validators. Never edit the failed platform version in place or fall back to an unversioned default.
- Set candidate routing to zero and preserve non-sensitive request IDs, effective version metadata and failing fixture.
- Atomically move the logical prompt pointer to the previous immutable application release.
- Verify the prior OpenAI prompt ID/version resolves in the approved project and local artifact hashes match.
- Run every consumer compatibility smoke plus critical policy, refusal and injection fixtures.
- Confirm runtime telemetry reports the previous complete release and normal validator/outcome metrics recover.
- Keep the failed release immutable for analysis, create a new dataset case and require a new platform and application version for correction.
Evidence