Documentation
The prompt spec: the single document that lets a stranger run, evaluate, debug, and safely change your system — assembled from artifacts you already have.
Then document. A prompt system nobody else can operate is a personal script, not production infrastructure. The prompt spec is the difference — one document, mostly assembled from artifacts you already made, that answers every question the next owner will have. This is deliverable 2, and for many employers the most impressive one.
The prompt spec — eight sections
- 1Purpose & owner — three sentences: what it does, who owns it, current version + date.
- 2Contract — input format (with one sample), output schema with per-field consumers and the null policy. Copied from your brief, updated to reality.
- 3The prompt itself — full text, versioned, with a change log table (version / date / change / eval delta). Your v0.x history is this table.
- 4Behavior notes — the decisions someone would otherwise re-litigate: why damage outranks returns, why three examples not five, why reasoning is capped at 4 steps. One line each; cite the eval evidence.
- 5Evaluation — golden-set location and composition, assertion list, judge rubric, current scores, holdout policy, re-run cadence.
- 6Guardrails — validation tiers, retry policy, routing table, circuit breakers. Paste the specs; they're already documents.
- 7Failure playbook — the three most likely incidents (validation spike, drift after model update, novel input class) and the first response to each, including the escalation human.
- 8Known limits — what it does badly, on the record: 'untested on non-English', 'multi-issue emails get first-issue-only', 'sarcasm degrades urgency accuracy'. An honest limits section is the strongest trust signal in the whole spec.
Write it, then test it like everything else
You are a competent engineer who has NEVER seen this system. Here is its prompt spec: [paste]. Attempt three tasks using only the spec: (1) explain to a stakeholder what it does and its limits, (2) tell me the exact steps to safely change one classification rule, (3) diagnose what to check first if valid-JSON rates suddenly drop. Where the spec left you guessing, list the gap.
The doc test, same logic as the golden set: don't argue about whether documentation is clear — measure. Fix the gaps it finds; run it once more.
A prompt spec with versioned changes, eval scores, and a routing table is rarer in the wild than working code. It's the thing to bring to the interview when they ask 'have you worked with LLMs in production?' — most candidates have prompts; almost none have specs.