Skip to content
Working with the tools, not about them

Workflows

Six months on, nobody can tell which parts of the document you decided

Keeping a record of the judgements made during a piece of work is more valuable than keeping the intermediate outputs, and it is the record almost nobody creates.

By Maya Chandrasekar3 min read

Editorial note. Independent reporting and analysis. Nothing here is sponsored or paid for. How we work.

The artefact does not show its decisions

A finished document has a smooth surface. It states what it states, and nothing in it distinguishes a number somebody checked against a source from a number that arrived in a draft and was never questioned, or a recommendation argued over for a week from a phrasing that survived because nobody objected.

That has always been true of written work, and the volume of material now produced makes it a practical problem rather than a philosophical one. When more of a document arrives as a draft to be accepted or amended, the difference between the accepted parts and the decided parts becomes the most important thing about it, and it is exactly the thing the document does not record.

The question arrives later, usually from somebody polite. Where did this figure come from. Did we consider the other option. Is this our position or a description of the common one.

A decision record is short and is not a log

What is worth keeping is not the sequence of drafts, which nobody will read, and not the instructions used, which answer a different question. It is a handful of lines recording the judgements: what was decided, what the alternative was, and why this one.

Three or four entries per document is a realistic target. We chose the narrower scope because the wider version would need data we do not have. The forecast figure is the client’s, unverified, and marked as such in the text. We removed the comparison section because it invited a question we cannot answer yet.

Each entry takes a minute to write at the moment the decision is made, and it is nearly impossible to reconstruct a fortnight later, which is why the timing matters more than the format.

Record what was accepted without examination, too

The uncomfortable half of the record is the material that entered the document without a decision. A background section nobody scrutinised, a definition taken as it arrived, a list that looked complete. These are not failures, they are ordinary, and knowing where they are is the difference between a document you can defend and one you can only hope about.

A simple convention is enough: mark passages as checked, as accepted, or as unverified while you work. Most of the value comes at review, because it tells the reviewer where to spend attention, and attention spent evenly across a document is attention wasted.

Strip the markings before the document goes out if that is appropriate, and keep the marked version. The marked copy is the one that answers questions later.

This is what makes the work defensible

When somebody challenges a conclusion, the useful response is an account of how it was reached. Being able to say that the alternative was considered and rejected for a stated reason is a different position from being unable to remember whether it was considered at all.

The same record is what allows a document to be revised safely. A later editor who can see that the scope was deliberately narrowed will not widen it by accident, and one who cannot see it will, because the narrow scope looks like an oversight from the outside.

In regulated or audited settings this may be a requirement rather than a good habit, and where that is so, follow whatever standard applies rather than a private convention. The point here is that the same practice pays off even where nobody is asking.

Keep it where the work is, and keep it small

The record has to live next to the document rather than in a separate system somebody has to remember. A short section at the end of the working file, a companion note in the same folder, or comments in the draft: any of these survive, and a well-designed log in a tool nobody opens does not.

Resist the pull towards completeness. A record that tries to capture everything becomes a chore, then becomes stale, then becomes misleading, which is worse than not having one. Three lines that are true beat thirty that were accurate a month ago.

And be clear about what this is not. It is not a defence against having decided badly, and it does not make an unverified figure into a verified one. It makes visible what was decided and what was merely accepted, and most of the value is in how uncomfortable that distinction is to look at.

Common questions

How does this differ from keeping the prompts or the drafts?

Those record how output was produced. A decision record captures what a person judged: the choice made, the alternative rejected, and the reason. That is the question people actually ask later, and it cannot be reconstructed from a pile of drafts.

What should be recorded besides decisions?

What entered the document without one — sections accepted as they arrived, definitions taken on trust, figures not checked. Marking passages as checked, accepted or unverified tells a reviewer where to concentrate, which is more useful than an even reading.

How long should the record be?

Three or four entries for a document, written at the moment each decision is taken. Attempts at completeness become chores, then become stale, and a stale record is worse than none because it misdescribes work somebody is relying on.

Workflowsprovenancerecord keepingaccountabilityhandover
Maya Chandrasekar
Senior writer, Prompt After Prompt

Maya writes about prompt craft, writing with ai, images & audio, mostly the parts other people skip and thinks most subjects are more interesting once you know how they work.