Sitrep

SITREP: brief the reader, do not narrate at them

The prime directive: reduce the reader's cognitive load

Every rule below serves this one, and where a rule seems to conflict with it, this one wins.

A report costs the reader attention whether or not it carries anything. They pay to read a sentence before they learn it was worth reading, so every sentence that changes nothing was taken from them. Thoroughness spends what it does not own.

Three tests, applied to the draft and not to the intention:

• Would they act differently for having read this? If not, cut it.
• Do they have to hold anything to answer? If yes, move it up.
• Could they stop at the first line and be right? If not, the first line is wrong.

Every failure this skill exists to name is the same failure: work moved from the writer to the reader. A buried ask makes them assemble the question. A wall of findings makes them sort. A resolved incident reported after the fact makes them read to discover there is nothing to do. None of those are dishonest. They are all expensive.

Someone asked a question. They want the answer, then the evidence, then what they have to do about it. They do not want to watch you think.

Before you write anything: run the check that settles it

Ask what one command would decide the question, and run it. A theory costs the reader a full read and leaves them where they started. The check costs you thirty seconds and ends the matter.

The signal you are about to get this wrong is having the numbers already. A session spent five exchanges on a failing gate, theorising about a category mismatch, then a broken harness, then an unpassable gate. It held three numbers the whole time: four tokens, thirty tokens, threshold 0.75. One division settles it. When it finally ran a thirty-second probe, the scores moved immediately and the theory collapsed.

So: if the question is arithmetic, do the arithmetic. If one call would show it, make the call. If a test exists, run it. Report what happened, not what you expect to happen.

This is upstream of every other rule here. A wrong theory delivered in perfect format is still wrong, and it costs more than any formatting defect, because the reader acts on it.

One trigger: the user asks for a sitrep, by name.

It used to fire on "investigate," "report," "resolve," "assess," "tell me," "what happened," "status," and on every screenshot. That was most of a conversation, so most of a conversation came back as a military brief. Adam narrowed it on 2026-08-28. Answer those in ordinary prose instead, following the writing skill.

Everything in writing applies to a sitrep too. The one exemption is the section labels below, and it covers the labels and nothing else. Inside them, write the way you would write anywhere: time order, one idea per sentence, the story rather than the anatomy, no self-labelling, no category-system openings. A sitrep is a report someone scans later, which is why it gets signposts. It is not a licence to sound like a briefing officer.

Why this shape

A report is read by someone deciding what to do next, and they stop reading the moment they have enough. Everything you place after that decision point is invisible to them, so the order of a report is not presentation, it is what survives. Putting the conclusion last hides it behind material the reader has already stopped needing.

The military convention exists because the cost of a buried conclusion is measured in something other than irritation. The same logic applies to an incident report, a pull-request description or a status update: the reader wants the answer, then the evidence for it, then the part that needs them.

The format

Use this shape whatever the verb. It scales from three lines to a page.

BLUF: <one sentence. The answer, the finding, or the recommendation.>

<whatever needs attention most, above anything needing less. Omit when
nothing does.>

FINDINGS
- <fact>  -  <the evidence, a number, a command output, a quoted line>

ASSESSMENT: <what it means. State confidence: confirmed / likely / unverified.>

ACTION
- Done: <what you already did>
- Needs you: <only what you genuinely cannot do yourself. Each item is a
  decision: brief it, do not list it. See rule 6.>

GAPS: <what you could not verify, and what it would take to close it>

Drop any section that is empty. Never drop BLUF and never drop GAPS when a gap exists.

The eight rules that get broken

1. BLUF is the first sentence, not the first paragraph. Not "Fixed and live." Not "Two things." Not a restatement of the question. The finding. If your opening sentence could sit on any other report, it is not a BLUF.

2. Rank by what needs attention, and count only what is still live. A reader stops at the top once they have what they need, so anything you bury you have hidden. If you were wrong in a way that still affects them, say so before you say what you fixed.

Ranked by attention rather than by tone, because "worst" sends a writer hunting for something to feel bad about and the hunt always succeeds. What ranks first is whatever the reader must act on soonest, and that is often a plain fact with no colour to it at all.

A failure you already repaired needs no attention, it is a diary entry. A theory you replaced before telling anyone is not a correction, it is your working. Both cost the reader a full read to establish they can do nothing with either.

The test is whether they would be misled without it, or have to act on it. "I broke dev and restored it, verified" fails both: it is fixed, and they were never going to touch it. "I told you the cause was X and it is not" fails both if you never acted on X. A session led with those two and was asked what made it think anyone cared. Nothing did.

Nothing needing attention is a result, not an empty slot. If there is nothing the reader must act on, the honest report is short or absent. Say that and stop. Promoting the nearest imperfect thing to fill the space is not thoroughness, it is manufacturing a finding.

2b. Do not size the claim to the effort. A large finding makes the hour you spent look like a discovery. A small one makes it look like you checked two things. That pull is real and it runs one way, so the claim you reach for first is usually bigger than the one you can defend.

A session spent an hour on a failing gate and reported "no prompt can pass this gate as wired." The defensible claim was "the two prompts I tried emit sentences, and the matcher needs labels." The second is smaller, correct, and points at a question someone can answer in a minute.

The test is mechanical. Write the claim, then ask what you actually observed. If you observed two cases, the claim is about two cases. If the general version needs a step you did not run, it is a hypothesis and belongs under GAPS with the step named.

Watch for the claim that grows between drafts. In that session it went from a shape mismatch to a broken harness to an unpassable gate, and the arithmetic that settled it, four tokens against thirty at a 0.75 threshold, was available before any of them were written.

3. Every claim carries its evidence on the same line. A number, a command output, a quoted line. "The homepage had no links" is an assertion. "anchors on the homepage: 0" is a finding. Never write "probably," "likely the cause" or "seems to be" in FINDINGS; those belong in ASSESSMENT with the confidence named.

4. Name the confidence. Confirmed means you ran it and saw it. Likely means the evidence points one way and you did not close it. Unverified means you are guessing, and guessing goes in GAPS, not in FINDINGS.

5. Report the whole result, including the part that failed. If a check did not run, say which. If a number is contaminated, say by what. A clean report of a messy result beats a tidy report that omits the mess.

6. A "Needs you" item is a decision, so brief it as one. The moment you write a line under "Needs you," stop reporting and hand off to the decision-brief skill. Put its recommendation in the BLUF, at the top, and give it options with what each costs and buys, plus the cost of doing nothing.

A bare line reading "Needs you: whether to commit this now" is the failure this format exists to prevent, wearing the format. It arrives 500 words in, it names no options, it prices nothing, and it asks the reader to reconstruct the decision from evidence arranged for the writer. Nobody can hold 500 words to reach it, and nobody should have to.

Two items means two briefs, or one brief with the choices numbered. Never a list of unpriced asks.

7. "Needs you" is only what you genuinely cannot do. Before writing a line under it, ask whether you could find the answer yourself in the next five minutes. If you could, go and find it. The list is for things blocked on something you do not have: a login, an account action, a message sent under their name, or a preference only they hold. It is not a place to put research you did not run, and a GAP is not a licence to leave the work undone. "I have not checked X, that would take an hour" is an hour you should have spent.

8. Effort is not a blocker, and calling it one manufactures a crisis. Three tests, and an item has to pass one of them:

• Capability. You cannot do it. A login, an account action, something sent under their name.
• Permission. You could, but it reaches outside and they should decide first.
• Preference that changes the work. You would genuinely build something different depending on the answer, and the choice turns on what they know or a cost only they can accept.

Anything else is work, and work is yours. "Slower per scenario" is not a cost to them. "Rebuilding it honestly means standing up a real database" describes a task, not an obstacle, and dressing a task as an obstacle asks them to authorise effort you were already going to spend.

This is real. On 2026-08-16 an agent reported "the four remaining groups are hand-written doubles, rebuilding them honestly means driving a real SQLite or Turso, slower per scenario, say real or double." Asked why that was a blocker, it answered: "It isn't. I already stood one up three times today in four lines each. That was me manufacturing a blocker." Its own report had already named the answer two paragraphs earlier.

Read your own report before writing the ask. If the evidence above the line settles it, you have answered it, and asking anyway spends their attention on a conclusion you already reached.

When nothing changed, the receipt is not a message

A turn that holds, waits, or acknowledges has no finding in it. It still has to end in text, so it ends in a paragraph describing a state the reader already knows, and they read the whole thing to discover that nothing happened.

Put that in a tool call instead:

echo "holding prod, nothing dispatched, waiting on your go"

The message then carries only what changed, which on such a turn is nothing, so it can be one line or none at all.

Why a tool call. Assistant prose and tool output are different channels in the client. Tool output folds; prose does not, and no hook can move text between them. Running a command to get its rendering is slightly perverse, and it is the only lever that exists.

What this buys, precisely. Folding is the smaller half, because a one-line receipt is one line wherever it sits. The gain is that the message stops carrying state. Someone scanning replies sees findings in the prose and nothing else, so a turn with no finding costs them a glance rather than a paragraph.

What it must not become. A receipt replaces the paragraph and never accompanies one. Writing the state in the message and echoing it as well doubles the reading and adds a command. A turn that did change something reports that change in the message as normal. This is only for the turn where nothing moved.

Screenshots

A screenshot means "look at this and tell me what to do," not "describe this back to me."

• Read what is on it. Do not recite it back; they can see it.
• Lead with what it means or what is wrong.
• If it shows a failure, that failure is the BLUF.
• If you need something the image does not show, ask one question. Do not speculate around the gap.

No coinage, and half the words

Use only words that already exist, in the meaning they already have. Do not invent a term. Do not repurpose an ordinary word for a new sense and then define it. Do not build a label from two ordinary words and treat the pair as a term of art.

Where a subject has its own vocabulary, use that and nothing else. Umbra says "unexercised input region." A session wrote "loose parameter," then "bare container," then "container," none of which were Umbra's. Each needed redefining, each redefinition was wrong, and the writing became impossible to follow. If no existing word fits, describe the thing in a sentence. A sentence the reader understands beats a coined noun they have to learn.

clarity.py gates the announcement of a coinage and cannot see the coinage itself. "Bare container" is two ordinary words, and only someone who knows the vocabulary knows it stands for something else. The check catches you saying you are naming a thing; it cannot catch you naming one quietly.

Then cut the draft in half. Whatever length it wants to be, that is twice what it should be. Delete the second explanation of a point already made, the table that restates the list above it, the measurement nobody asked for, and the plan offered before it was wanted.

Nothing measures this. Half of what a draft wanted to be is not in the draft, and a word ceiling would gate brevity rather than value. The test is per sentence: does the reader need this to act? A report that survives its own deletion pass is the one worth sending.

Length

The report is not the work, and length is not evidence of effort. A one-line fix gets a three-line report. Padding one out with structure signals thoroughness while costing the reader the time that thoroughness was supposed to save them.

• Two headings maximum. More means you are performing thoroughness.
• No table for fewer than three rows.
• Cut every sentence that only announces the next sentence.

Before sending, run it

uv run tools/clarity.py draft.md    # or pipe on stdin

Fix what it flags, then send. It prints your first sentence back at you, which is the check most often failed. The band is 20 to 40: under 20 you have cut meaning out, over 40 it takes two passes.

Then four operations: first sentence carries the finding, ranked by what needs attention, headings counted, em dashes counted.

Worked example

Bad, and this is a real report, rewritten after review:

Fixed and live. The earlier empty reads were cached copies.

What was actually wrong

...five sections, the admission of error fourth...

Good:

BLUF: honestframework.software had zero links on its homepage, so no crawler could get past it. Fixed and live.

I got this wrong twice. I told you it was authority and that no technical fix would help. It was markup both times.

FINDINGS

• anchors on the homepage: 0, ten buttons driven by JavaScript
• GPTBot, ClaudeBot, Google-Extended, PerplexityBot: each fetched "/" only, never deeper
• the ten "deep fetches" I reported earlier were ChatGPT user-fetches, not crawls

ACTION

• Done: 20 canonical links on the homepage and in llms.txt, commit 520155c, deployed
• Needs you: nothing

GAPS: whether crawlers take the path is theirs to decide. Needs a re-crawl, so weeks. The monitor tracks it daily.