What has to be recorded about a drafting run for a generated case to be explainable months later?

## The question an old generated case provokes A year after it was merged, nobody asks what a generated case does - the code says that plainly enough. The question is always some form of **why does it assert this**. A colleague wants to delete it and needs to know whether the assertion encodes a requirement or a guess. A behaviour is about to change and someone must decide whether the case is protecting intent or protecting an accident. A batch of similar drafts turns out to be wrong the same way, and the useful question is what they shared in their input. None of those are answerable from the code, and none are answerable from the person who merged it, who has forgotten or left. They are answerable only from the **inputs that produced the draft**. That is what a drafting record is for: it exists so a machine-drafted case is no more mysterious a year later than a hand-written one whose author wrote a decent commit message. ## What to record Record the inputs and their versions, not the conversation: 1. **The request text**, exactly as sent - the words that framed what was wanted. 2. **Each attached artefact with its revision.** This is the field people skip and the one that matters most: which acceptance-criteria document, at which revision; which redacted sample record; which rulebook; which exemplar cases, at which commit. A reference without a revision points at today's text, not the text that was in force. 3. **The drafter identity and its settings** - which build produced it and how much randomness was allowed. Behaviour changes across builds, and a family of odd drafts often shares one. 4. **The raw output**, before any human edit. Without it you cannot separate what the machine produced from what a person then repaired, which is precisely the distinction a later reader needs. 5. **The human edits**, as a short note or a difference against the raw output. 6. **The identifier of the case as merged**, so the link runs in both directions. ## Provenance is not replay This is the part that is most often misunderstood, and the misunderstanding leads people to abandon recording altogether when the first rerun disagrees. | Question | Does the record answer it? | |---|---| | What was the drafter given, and at which revisions? | Yes - this is its whole purpose | | What did the drafter produce before human editing? | Yes, if the raw output was stored | | Which parts were repaired by a person? | Yes, from the recorded edits | | Will the same request reproduce the same case? | No - sampling and build drift make that unavailable | | Was the resulting case correct? | No - provenance never certifies correctness | Sampling makes generation nondeterministic, and the build moves under you regardless. Byte-identical replay was never on offer, so its absence is not a defect in the record. Aim at **explainability**: a reader can reconstruct what the drafter knew and therefore judge whether the assertion had a basis. That is the question people actually bring. ## Where the record lives, and how the case points at it A record nobody can find is not provenance. Two properties make it usable. First, the record has a stable identifier and the merged case carries that identifier in its own metadata or header comment, so the trail is one lookup from the file in front of you. Second, the record is stored somewhere with the same lifetime as the code; a link into a chat product's history is a link that outlives nothing. The direction matters. Searching a drafting archive for a case is hopeless; following a pointer from a case you are already reading is trivial. Put the pointer on the case. ## What not to record, and why transcripts disappoint The tempting shortcut is to keep the whole conversation. Transcripts are long, awkward to search, and mix the inputs that mattered with dead ends - but the real weakness is subtler. A transcript contains context that was **pasted**, and pasted text carries no provenance of its own. You can read the criteria that were supplied and still have no way to know which revision of the criteria document they came from, or whether the sample record was the checked one. The transcript preserves the words and loses the versions, which is exactly backwards. Keep transcripts if they are cheap, but do not mistake them for a record. What you need is references with revisions. ## Who reaches for it Three groups, and it is worth knowing which one you are building for. Engineers changing or deleting an old case, who need to know whether the assertion has a basis; reviewers investigating a cluster of similar bad drafts, looking for the shared input that caused them - this is the use that pays for the whole scheme, because a bad rulebook rule or a stale criteria revision explains dozens of cases at once; and, in regulated work, anyone required to show how a control was produced. Size the scheme to those three. A record that takes ten minutes to fill in by hand will not be filled in, and an empty archive explains nothing. Capture it automatically from the drafting step or accept that you will not have it.