---
name: "prompt_versioning"
description: "Version prompt text like source code: keep a change log, diff versions side by side, pin a known-good version for production, and roll back when a change misbehaves. Use when a prompt is shared, reused, or changed over time and someone asks what changed, whether you can roll back, or which version is live."
metadata: { "includeInPrompt": true }
---

# Prompt Versioning

## Purpose

Prompts change silently and behavior shifts with no record of why. One edit to a system instruction, one reworded line, and a product behaves differently for everyone who uses it. Treating prompt text like source code, versioned, diffable, and rollback-able, fixes that. This skill covers the file-level discipline: how to store prompts, how to log changes, how to pin the version that is live, and how to roll back.

## Workflow

1. One prompt, one file. Store each prompt as plain text in its own file (for example `prompts/support_triage.txt`). No embedding prompt text inside scripts or scattered config files where nobody can find it.

2. Log every change. Keep a change log next to the prompt (for example `prompts/support_triage.log` or a shared `prompts/CHANGELOG.md`). Each entry has three things: the date, what changed, and why. One or two lines is enough.

```
2026-10-05  Added "Ask for the order number before anything else." Reason: the bot kept guessing which order the customer meant and got it wrong half the time.
2026-10-03  Softened the refund refusal to offer a callback instead. Reason: too many angry escalations in the support inbox this week.
```

3. Diff versions side by side. Before shipping a change, read exactly what moved. Standard `diff` works fine:

```
diff prompts/support_triage.v3.txt prompts/support_triage.v4.txt
```

Read every line of the diff out loud to yourself if the change matters. Most silent breakage is a word that looked harmless.

4. Pin the live version. Production points at a pinned, known-good copy, never at the draft you are editing. The pin is a tiny marker: a file or a line that names which version is live.

```
LIVE: prompts/support_triage.v4.txt
```

Edit only draft copies. Update the pin only when a new version is deliberately shipped, and log that in the change log too.

5. Roll back on a misbehaving change. Rollback means: point the pin back to the last good version and note why in the change log. No code rewrites, no frantic re-editing under pressure.

```
2026-10-05  Rolled live pin back to v4 from v5. Reason: v5 dropped the order-number ask and the misfires returned within an hour.
```

## Output Contract

A versioned prompt bundle looks like this:

- The prompt file itself, plain text, one per prompt.
- A change log with dated entries, each stating what changed and why.
- A pinned-version marker naming exactly which version production uses.

A rollback looks like this: the pin now points at an older version, and the change log has a new entry recording the rollback, the date, and the reason. That is all. If any of those three artifacts is missing, the bundle is incomplete.

## Operating Rules

- Never edit the pinned production copy in place. Edit a draft, ship it, then move the pin.
- A change log entry without a reason is filler. "What changed" alone tells you nothing when the next problem arrives. Always write the why.
- Date every entry. An undated log is a diary with the pages shuffled.
- Keep one canonical location for the live pin. If two places disagree about which version is live, you have no live version.
- Name versions sequentially and keep old ones around. Deleting the version you rolled back to is how a second outage starts.
- When someone asks "what changed", answer from the change log and the diff, not from memory.