A prompt written for someone else has to carry the context you never typed

What worked was you, not only the wording

An instruction you have used for months feels complete because you have never once run it cold. Every time you used it you also chose the input, judged the result against a standard you never wrote down, and quietly re-ran it when the first answer came back thin. Your colleague inherits the wording and none of that.

So the failure report reads oddly from both ends. They say it produces something vague and slightly off; you run the same words on your own material and get exactly what you always get. Nothing has changed except the person, and the person was carrying half the specification.

The diagnostic is uncomfortable but quick. Run your own instruction against an input you didn’t pick, and accept the first result without touching it. What comes out is roughly what the next person will see, and it is usually a good deal worse than the version you remember.

The input will not be the one you developed it on

Instructions absorb the shape of the material they were built against. If you always fed it a two-page document with headings, the wording quietly assumes headings exist. Hand it a transcript, a spreadsheet export or a forwarded email chain and the assumption breaks somewhere in the middle, without any part of the output announcing that it broke.

A shareable instruction therefore has to describe its own input. What kind of document, roughly how long, in what state, containing what at minimum. That description isn’t bureaucracy — it is the only thing standing between your colleague and a confident answer drawn from material that never contained one.

Then say what to do when the input doesn’t match. Stop and say so is a perfectly good answer, and it is far better than the alternative, which is a plausible output built on a source that was missing the section the instruction depended on.

Name the judgements you have been making silently

Every time you accepted an output you applied criteria. Too long, wrong register, buried the important part, sounds like marketing. Those criteria are real and consistent, and none of them are in the prompt, which is why the prompt looks so much shorter than the job it actually performs.

Writing them down is the bulk of a handover. Not as adjectives, which mean different things to different readers, but as decisions: what goes first, what gets left out, what length, whose vocabulary. A colleague who knows those four things can judge an output; one who does not will accept whatever arrives.

This is also where you discover that two of your criteria conflict, because you have been resolving the conflict by feel. Resolve it explicitly instead, and say which one wins. The instruction gets slightly worse for you and considerably better for everyone else.

Show them a result you accepted, for their benefit rather than the tool’s

Attach one output you were happy with, and if you can, one you rejected with a line on why. This is calibration for the person, not material for the model, and the distinction matters: it is telling a colleague what the finish line looks like when they have never seen you cross it.

The rejected example is the more useful of the two, because it fixes the boundary. Plenty of output sits in the region that is fluent, competent, and not what you wanted. Without a sample of that region, a new user has no way to tell the near-miss from the hit.

Keep both with the instruction rather than in a separate place. A prompt stored on its own gets copied, pasted and gradually reworded until it is a different instruction that nobody remembers deciding to write.

Say what may be changed and what may not

Some parts of an instruction are load-bearing and some are decoration. The requested structure is usually load-bearing, because something downstream reads it. The phrasing about tone usually is not. If you do not mark the difference, the first person to tidy the wording will remove the sentence that was doing the work.

A short note is enough. Two lines saying which requirements are fixed, which are adjustable, and what the output feeds into afterwards will survive several rounds of editing by people who were not there when you wrote it.

There is a point where this stops being worth it. If the task needs your judgement at three separate moments, you are not writing a shareable instruction, you are writing a training document for a skill — and it is more honest to say so than to hand over a paragraph that will only work for the person who wrote it.