A prompt states a goal and gets out of the way. Everything else in it is load — spent on every run, taken from the attention the model would otherwise put on the work — so each line has to buy more than it costs. What follows decides four things: what the run is given, whether a line exists, where it sits, and how it is worded.
What the run has in front of it
A run's result is bounded by what it has in front of it: the prompt and everything fed into it — the inputs filled into a template, the files it reads, retrieved material, tool output, the conversation so far, what a handed-off agent receives. The model is usually capable enough, so bad output usually traces to that input. When a run underperforms, read what it actually had — the trace or the filled-in input, not the template alone — before you change any wording, and look for four faults:
- Missing — a piece the task needs is not there, so the run guesses.
- Conflicting — two pieces disagree, so the run picks one.
- Wrong or stale — a piece is untrue or out of date, so the run repeats it.
- Noise — what matters is there, buried under material that does not bear on the task.
Fix the input first: supply the piece or a pointer that reaches it, choose one source where two disagree, correct or drop what is wrong, cut what buries the signal. That usually moves the result more than any other change. Wording edits and after-the-fact corrections — a review pass, a self-check, a rule added after a failure — come after it. A correction that makes up for faulty input leaves the fault in place, and the next run meets it again.
Complete means complete for the task: the fix usually trades noise for the missing piece rather than adding volume. Look to the instructions when the input is already complete, consistent and clean; when the model lacks a capability no input can supply, change the architecture instead.
Where a line came from
Ask this before asking whether the line helps. A line can be true, relevant, and still worth cutting, so usefulness does not settle it. Provenance does, and you can answer it from memory:
- The user ruled it — a decision, preference, or constraint they stated. Nothing derives it. Keep.
- The world holds it, out of the run's reach — an unwritten convention, a failure you observed, a fact outside what the run will read. Keep, and prefer a pointer to the source over a copy that can go stale.
- It counteracts a default you have watched the model take — keep, when the default is observed rather than feared.
- You worked it out from material the run will also read — cut. A conclusion available in the corpus is one the run reaches itself, so writing it down buys nothing and spends load on every invocation.
That last class is the one that feels most earned, because you did the work to reach it, and it is where over-specification comes from. Two tells: a line you could justify from the same sources the run gets, and a sentence that merely argues for the instruction above it without adding information admitted by the tests above.
A choice the request left open belongs to whoever made the request. Some of what you would add is not padding but a decision — what ranks one candidate over another, an exception to a rule they gave you, a deliverable beyond what they asked for. It reads as thoroughness and it commits them to something they never chose, under their name, in a file they will quote back later. Ask where the answer would change the work; leave it out where it would not.
A finished prompt looks thinner than you expect it to, and that is the result rather than a warning sign. Two rulings and a goal make a short document; the pull at that point is to fill it out — a section on how to rank, a definition of the term in its own name, a third source of evidence nobody asked for — and everything reached for that way comes from the class above. When it reads as too slight, check the goal is stated and the rulings are in it, then ship it.
The counterfactual question — would the model do this without the line? — asks for a prediction about the model's own behaviour, which is not reliably answerable from the inside. Ask it second, of what provenance already admitted: it can still cut a line provenance allowed, never keep one provenance rejected.
When two people disagree about whether a line is doing work, the argument is about the model's default, so settle it by running the document with the line removed and comparing. That is a tiebreak available when it is worth the trouble, not a step every line has to pass.
Author upward
Start from the goal sentence. Add only what the questions above admit, one line at a time.
Writing broadly and pruning afterwards costs more and lands longer: every line you would cut is one you already argued for, and the draft's own weight reads as evidence that it was needed.
Two budgets
Everything you add spends one of two things:
- Context load — always-loaded material, paid every turn whether or not it fires. A skill's description, a rule in an
AGENTS.md, anything resident. - Cognitive load — what a person has to hold: which documents exist, and when to reach for each. Not a cost to drive to zero — it is what buys human judgement. Spend it where judgement matters.
Material behind a pointer escapes context load for the price of the pointer's own line. Material with no pointer rides entirely on a person remembering it.
Where a line sits
Three rungs, ordered by how immediately the run needs the material: steps it performs in order, reference it consults on demand, and disclosed reference in a separate file reached by a pointer. Moving material down keeps the top legible; moving too much down hides what the run actually needs. Branching decides it — inline what every path needs, disclose what only some paths reach.
Keep a rule's statement, its bounds, and its exceptions together under one heading, so reading one brings the others. A rule split across a document is one rule that can drift into two.
A pointer is the line naming out-of-context material and the condition for reaching it: a skill description, a reference link. Its wording, not its target, decides whether the run gets there — so lead with the word that triggers it, give one trigger per distinct case, and cut what the target already says about itself. If material must be reached and the pointer is weak, sharpen the wording before inlining the material.
Wording
Reach for a word the model already holds. A pretrained word — relentless, tight, adversarial — recruits priors and anchors a region of behaviour in one token, where a phrase spends several and lands weaker. When a directive is too weak, the fix is a stronger word rather than more words. A coined term recruits nothing, so you pay in definition what a real word gives free.
The same activation scales from a word to a discipline. A pretrained concept — adversarial verification, rival explanations, goal-based — activates everything the model already holds about practising it, so a firm goal plus a few such concepts can stand in for pages of process the model would re-derive anyway. Prefer that shape for a whole prompt: state the goal and the rulings that bind, name each discipline by the words that recruit it, and leave the manoeuvring to the model. The backbone stays firm because the goal and rulings bind — not because every step is written down; spelled-out process constrains a capable model to one path where the latent discipline covers them all.
State the target, not the ban. A prohibition names the behaviour it forbids and thereby makes it available — the negation is a weak modifier on a strongly activated concept. Write one-line comments beats don't write long comments. Keep a prohibition only as a guardrail that cannot be phrased positively, and pair it with the positive target.
End every step on a condition the run can check. Understanding reached invites stopping early, because the steps still visible ahead pull attention toward being done. Sharpen the bound first; splitting the sequence only helps across a real context boundary, since an inline mention leaves the later steps in view. Wording also sets how much work the step demands: every caller enumerated forces the sweep that list the callers does not.
Give judgment calls a rule, not an absolute. Always ask before assuming over-fires; when the missing fact would change the action, ask — otherwise proceed and label the assumption can be applied. Reserve MUST and NEVER for real invariants.
Keep the arousal low. Urgency framing, all-caps imperatives and heavy praise measurably shift behaviour — toward corner-cutting under pressure, toward agreement under flattery. Normalize failure in anything iterative: if this approach doesn't work, try another. The opening sets the register for everything after it.
Pruning
- One meaning, one place. The same rule in two files is two texts that drift, and only one of them will be read. (Repeating a word on purpose is the opposite move and is fine.)
- The environment is a source of truth. A prompt restating what
package.json, a config file, or--helpalready answers is a cache that goes stale. Cache only what no file confesses: the unwritten convention, the reason, the gotcha. - Check every line for relevance, not just correctness — a line can be true and no longer bear on what the document does. Left unchecked, a prompt accretes layers nobody dares remove.
- Hunt no-ops sentence by sentence. An instruction the model already follows pays load to say nothing. Delete the whole sentence rather than trimming its words.
Edges
A line can earn its place and still break where the prompt actually runs. Check each against the conditions it will meet:
- Naming a harness-bound primitive — a specific tool, scheduler, or CLI — where the capability should be stated in plain language and the model left to find it.
- A qualifier that quietly excludes cases the principle covers (under mode X, by another reviewer).
- A mechanism stated as the only path — a fixed sequence, a hardcoded number — where the principle should stand and the number be a default.
Updating
When the change follows a bad result, start with What the run has in front of it, and change the prompt's lines only for what the input does not explain. Find the gap a line closes before changing anything near it. The best patch usually replaces a line rather than adding one beside it, and a new explicit rule often retires an older vague hedge. Net change can be positive or negative; the target is balance, not direction.
The updated prompt reads as if written today for what it now does. What a line used to say, when or why it changed, and who asked for it go in the commit message or a decision record, outside the prompt's file: in the prompt they cost load on every run and can be followed as instructions. Why a rule holds can stay. Keep the ruling, not the note that it was ruled.
After the edit, reread the whole file as a newcomer would, not only the lines you touched: each rule stated once; nothing that contradicts or repeats the new line; the opening still describing what the prompt does. Remove history notes and the hedges a new rule retires wherever they sit: removing them changes no rule, so it is not a choice left to the requester.
Guard against building a wall around a single observed failure. One instance is a fix; a section is over-correction.
References
references/mechanics.md— the shapes: a skill's frontmatter, naming and layout; an agent's isolation and capability declarations; a knowledge skill whose gap is data rather than behaviour.references/system-prompts.md— a system prompt that ships in a deployment loop, and the ready-made blocks for one: verification passes, tool-call budgets, ambiguity handling, output contracts, high-risk self-checks. For that artifact only.references/metaprompting.md— diagnosing a failing prompt against logged traces.
