---
name: prompt-suite-versioning
description: "Improve a prompt as a versioned artifact with a score, change one variable at a time, keep the diff, read the failures. Use whenever editing prompts that must stay measurably good."
version: 1.0.0
author: Zorost Intelligence
license: MIT
metadata:
  zorost:
    tags: [prompting, versioning, context-engineering, build]
    related_skills: [eval-first-development, context-budget-audit, error-analysis-50]
    program_weeks: [6]
---

# Prompt Suite Versioning

## 1 · Purpose

Turn prompt editing from taste into engineering: every version has a score, every
change is one variable, every regression is reversible.

## 2 · When to use

- Improving, refactoring, or "cleaning up" any production prompt.
- Adding few-shot examples, schema constraints, or injection rules to a prompt.

Do **not** use to draft the very first prompt of a brand-new task, draft freely,
then enter this loop the moment a scorer exists (`eval-first-development`).

## 3 · Inputs

- A golden set and scorer (`eval-first-development`) with a recorded baseline.
- The current prompt, saved as a file (not living only in code or chat history).
- A versions log: `prompts/log.md` or the eval results directory.

## 4 · Procedure

1. Save the current prompt as `v{N}.md` and record its baseline score. If it has no
   score, score it now, this is the number every later version must beat.
2. Pick **one** variable to change: one system-prompt line, one example, one schema
   field, one formatting rule. Write down the hypothesis: "adding the null rule will
   fix the missing-field hallucinations."
3. Create `v{N+1}.md` with exactly that change. No drive-by edits.
4. Run the scorer. Record version, score, and the one-line reason in the log.
5. If the score dropped, revert without debate. If it rose, keep it. If it is flat,
   decide by cost: keep the cheaper or simpler version.
6. Read the failures of the new version, not the score alone. Cluster them. If a
   failure class is new, add a case for it to the golden set *with a commit message*.
7. Repeat from step 2 until the score clears the spec gate or three consecutive
   versions fail to move it. On the third flat version, STOP and report: the prompt
   axis is exhausted; the lever is elsewhere (retrieval, model, data).
8. Keep every version file. Disk is cheap; archaeology is expensive.

## 5 · Anti-rationalization

| Excuse | Answer |
|---|---|
| "This change is obviously safe." | "Obviously safe" prompt edits are the leading cause of silent regressions. Score it. |
| "I'll batch these three tweaks to save time." | Then you will never know which one helped, and you will re-learn it next month. |
| "The eval is slow; I'll just eyeball this one." | Eyeballing is how v1 shipped with a carrier-suffix bug. Run the scorer. |
| "Deleting old versions keeps the repo clean." | The old version is the rollback. Keep it. |

## 6 · Red flags

- Prompt text lives only inside application code with no version file.
- The log has scores without the version they belong to.
- Three variables changed between two consecutive versions.
- The golden set shrank at any point in history.

## 7 · Verify

- `prompts/` contains every version, and the log maps version → score → reason.
- The current production version's score clears the spec gate on the frozen golden set.
- At least one failure-class case was added to the golden set from observed failures.

## 8 · ZoroLogistics example

Week 6's BoL suite: v1 zero-shot scores 0.61 (junk suffixes, hallucinated values).
v2 adds the JSON schema + null rule → 0.83; failures cluster on scan noise. v3 adds
one few-shot example of a noisy scan + the injection rule → 0.92, clearing the gate.
The log shows exactly which single change bought each jump, and the golden set grew
by four adversarial cases found along the way.

---
© 2026 Zorost Intelligence LLC · zorost.com