We rebuilt PromptSewa — and your prompts were reset

Lesson 19 · 5 min

Versioning and documenting prompts

A prompt without a history is a prompt you cannot improve. Treat it like code.

A prompt that works is an asset. Assets need history: what changed, why, and which version produced the output people trust. Without that record, every improvement is a gamble and every regression is a mystery. Prompt versioning is not bureaucracy; it is the difference between a prompt you maintain and a prompt you are afraid to touch.

One version, one reason

Every version should have a one-line changelog that names the reason: "added a 120-word cap", "replaced examples with two edge cases", "split the extraction into two steps". A version without a reason is not a version, it is a save. When a later regression appears, the changelog is what lets you find the change that caused it.

Keep prompts append-only

Never edit the version that is currently in use. Add a new one. This is the same rule the PromptSewa catalog applies to prompt versions: an existing row is history, and history that can be rewritten is not history. It also means a buyer or a teammate can always retrieve the text that produced a specific result, which is what accountability looks like in practice.

Document the contract, not just the text

Beside each prompt, record what it expects and what it guarantees: required variables, allowed values, output shape, known limitations. That documentation is what lets someone else use the prompt without reading your mind. It is also what you will have forgotten in three months. A short header comment or a listing description covers it.

Example: "v3 — extracts vendor, invoice number, total and due date from one invoice. Requires {{document}}. Returns JSON; null for absent fields. Known limitation: two invoices in one file are not supported."

Track the evaluation set with it

The test cases are part of the prompt's specification. Keep them in the same place as the prompt so a version and its evidence travel together. When you change a prompt, run the set. When you add a case, note which version it was added under. This is what makes a claim like "this prompt is more reliable" checkable rather than a feeling.

Retire deliberately

Old versions should be marked retired with a date, not deleted. Someone may still be running an old copy, and a retired version with a reason is a useful historical record. For a marketplace listing, that history becomes part of the product: buyers can see the prompt has been maintained, and creators can explain what improved.

Checklist

  • Does every version have a one-line reason?
  • Is the in-use version immutable?
  • Is the contract documented next to the prompt?
  • Do the evaluation cases live with the version?

Finished this lesson?

Mark it complete to generate a certificate you can print or save as a PDF. We ask for an email only so you can be reached — no account is created.

All lessons