# Pathrule Pattern: Prompt Versioning and Management (1.0.0) # ::pathrule:package:prompt-versioning-management ### [RULE] Published prompt versions are immutable complete artifacts (path: /src/ai/prompts) A prompt is more than its instruction text. Publish an immutable artifact that includes ordered messages or template sections, typed variable definitions, required and optional inputs, model or capability intent, sampling and length settings, tool definitions, output schema, safety and data-handling policy, owner, source revision, and change reason. Never edit a version after it has produced traffic. - Validate unknown, missing, empty, oversized, and incorrectly typed variables before provider submission. - Escape or delimit untrusted values according to the prompt's threat model rather than interpolating raw content casually. - Give semantically identical artifacts one stable content identity and semantically different artifacts distinct versions. - Store provider-managed prompt ids as deployment references, not as the only source of the reviewed artifact. Verification: Reconstruct an old request from its recorded artifact and inputs; confirm it resolves the same messages, tools, schema, and configuration without consulting mutable latest state. --- ### [RULE] Every generation pins an approved release version (path: /src/ai/runtime) Never let production traffic follow an unversioned latest prompt. A release record points to one immutable prompt version, compatible model and fallback policy, tool implementation versions, output parser, evaluation result, approver, rollout allocation, start time, and rollback target. Runtime resolves the release once per generation and records the chosen identity. - Gate promotion on the required offline evals, contract tests, safety checks, and representative manual review. - Roll out by a stable assignment key when comparison or canary traffic requires consistent user experience. - Keep a known-good release immediately restorable without rebuilding or editing the artifact. - Stop or roll back on predefined quality, safety, latency, error, and cost signals rather than waiting for anecdotal reports. Verification: Promote, canary, retry, fail over, and roll back a version while traffic is active; confirm every generation maps to exactly one complete approved release. --- ### [MEMORY] Prompt compatibility includes callers, tools, and outputs (path: /src/ai/prompts) Treat prompt compatibility as an interface contract. Identify application callers and their variable shapes, the tool names and argument schemas the model may invoke, output formats and parsers, fallback models, safety filters, localization variants, retrieval context, and downstream effects. A change is breaking when any consumer must change or when the same input can now trigger a materially different side effect. Version tool and output contracts explicitly and test prompt-model combinations that production can select. Use migration or dual-read paths when old sessions, cached inputs, queued jobs, or persisted tool calls outlive a release. See /src/ai/runtime for release pinning and /tests/evals for behavioral evidence. --- ### [MEMORY] Prompt identity participates in cache and trace identity (path: /src/ai/runtime) A cache entry created under one prompt can be wrong under the next even when user input is identical. Include the prompt artifact or release identity, model and material settings, tool and output schema versions, retrieval corpus version, safety policy version, and normalized input contract in cache identity according to the feature's semantics. Attach the same identities to traces, token and cost records, user feedback, evaluation samples, incident cases, and support views. Preserve privacy by logging references and approved hashes rather than raw sensitive prompt content. This makes regressions attributable and rollback measurable. See the LLM Observability and Tracing pattern for telemetry boundaries. --- ### [SKILL] publish-prompt-version (path: /src/ai/prompts) --- name: publish-prompt-version description: Publish an immutable prompt version with contract, evaluation, approval, rollout, and rollback evidence. --- # Publish Prompt Version 1. Diff messages, variables, model intent, settings, tools, output schema, safety policy, retrieval inputs, owner, and affected callers against the active version. 2. Classify compatibility and update contract tests, persisted-session handling, caches, parsers, tool implementations, and fallbacks where required. 3. Run the required representative, adversarial, safety, deterministic, cost, latency, and model-compatibility evaluations; retain dataset and rubric versions. 4. Create the immutable artifact and release record with reviewer, change reason, rollout key, monitoring thresholds, and known-good rollback target. 5. Canary the version, compare predefined signals, promote or roll back, and link production evidence to the exact release. Do not publish from an editable draft or a passing average that hides a critical regression slice. --- ### [SKILL] rollback-prompt-release (path: /src/ai/runtime) --- name: rollback-prompt-release description: Roll back a prompt release as a complete runtime artifact while preserving incident evidence. --- # Roll Back Prompt Release 1. Freeze the affected release ids, assignment keys, time window, models, tools, schemas, retrieval versions, safety policy, metrics, feedback, and representative failing traces. 2. Stop further promotion and route new generations to the recorded known-good release without editing either artifact. 3. Confirm caches, queued jobs, persisted sessions, fallbacks, and retries cannot continue selecting the bad or an incompatible mixed configuration. 4. Verify quality, safety, error, latency, and cost signals recover, then classify affected outputs and any downstream side effects. 5. Add the failure to eval and contract coverage, create a new corrected version, and use the normal staged release path. Rollback is complete only when every generation can be attributed and mixed-version behavior is excluded.