Prompt versioning, storage and review

Read these first

• Prompt templating and escaping user input
• Evaluation in CI

What you will know

• Put prompts under version control and code review

  A repository provides authorship, diffs, approvals, and a durable audit trail for behavioral changes.

• Roll back a prompt change without a deploy

  The serving path must be able to select a previously approved artifact through configuration or a control plane.

• Trace a given production output to the prompt version that produced it

  Without correlated request metadata, model settings and retrieved context can make the same symptom impossible to reproduce.

• Treat a prompt change as a migration with a rollout plan

  Stage exposure, define success and guardrail metrics, and keep a rapid abort path because wording can change tool use and user-visible behavior.

• Audit a prompt edited in a UI with no history and replace it with a reviewable workflow

  Unattributed console edits defeat rollback and make it impossible to distinguish prompt effects from model, data or configuration changes.

Chapters

1. 1

   Prompts are behaviour changes, so they need authorship and approval

   A forty-line wording tweak can move refusal rate, tool selection and cost as much as a code change, yet it often ships with no author, no diff and no reviewer. This chapter establishes what putting a prompt under version control and code review actually buys: attribution, a readable diff, an approval record, and a durable trail you can walk backwards when behaviour regresses weeks later.

   Read chapter
2. 2

   Why a prompt in the application repo makes rollback a deploy

   Keeping prompts as constants in the service repo gives you review, but it welds the prompt's lifetime to the release's. At 02:10 with tool-calling errors at 18%, undoing forty lines of text costs a build and a pipeline, and drags back an unrelated database migration and two feature commits unless somebody cherry-picks under pressure. Recovery time here is a property of your deployment path, not of the edit.

   Read chapter
3. 3

   Pinning an approved revision so rollback becomes a configuration change

   Separating where a prompt is authored from what the serving path resolves at request time is what turns a fourteen-minute revert into a switch. You will see how an immutable revision id, a pinned pointer and a control plane combine, and why the repo-versus-platform argument is decided by which system is authoritative at serving time and whether writes to it carry approval, not by whether there is a web editor.

   Read chapter
4. 4

   The prompt store you just pinned is now a serving dependency

   Resolving the active revision at request time means the control plane can be unavailable, stale or slow at the moment a request arrives. This chapter covers what serves when it is: a fallback revision bundled with the build, the cache TTL that decides how long a pointer flip takes to reach every instance, and the gap between flipping the pointer and the last worker honouring it. It also settles what stays in the repository regardless, so an outage of the platform degrades to the last approved artefact rather than to no prompt at all.

   Read chapter
5. 5

   A revision id alone will not reproduce yesterday's answer

   Logging the exact prompt revision behind every response feels like closing the loop, until you replay last week's complaint through that revision and get a different, perfectly good answer. The pins still missing are the model version, the decoding parameters and the ids of the chunks retrieved that day. Here you learn the request-level metadata that makes a production output genuinely reproducible.

   Read chapter
6. 6

   Splitting a reformat from a rule change in a prompt diff

   A pull request that reorders sections, rewraps text, renames two placeholders and quietly alters when the agent asks a clarifying question shows every line modified, which makes the review unreadable and the history unbisectable. This chapter argues the reviewer's real job: send it back as two revisions, one behaviour-neutral and one behavioural, and shows what that discipline is worth during the next regression hunt.

   Read chapter
7. 7

   Staging a prompt rewrite the way you would stage a schema migration

   Two approvals, green CI and three points better on a frozen eval set say nothing about the paths that eval set never touches: which tools get called, how arguments are filled, when the agent gives up. You will lay out staged exposure, the guardrail metrics that gate each stage such as tool-error rate, escalation, refusal, latency and cost, and an abort path that does not wait for a release. Then you will size the process to the risk, because a low-traffic internal tool, a prompt with no tool access, or a change a fast abort path can undo in seconds does not earn a slow ramp.

   Read chapter
8. 8

   Auditing a console-edited prompt before you freeze it

   When three people have edit access to a vendor console that shows only the current text, revoking access today freezes whatever happens to be in the box, which may be the drifted version rather than the good one. Work through the audit that reconstructs what changed and when, the reviewed artefact the serving path pins instead, and how the person who was iterating keeps a fast loop off production traffic.

   Read chapter