Sitrep

Chalk Sitrep — Where the Session Has Got To

Interpret MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, etc. per RFC 2119.

A sitrep is written for whoever picks the session up next — the user after a break, a future agent after a compaction, or the user's colleague reading over their shoulder. It is not a log of the session. It is the state the session has reached, and what still needs a decision.

$ARGUMENTS, if given, narrows the scope; report only on that and say in one line what you left out.

Before you write

• Load chalk:voice — the register, every parent a claim its children back up, and the typed-ID scheme the Open section runs on.
• Its register applies; its palette doesn't. A sitrep is a terminal reply, not a GitHub artefact: no sections drawn from the palette, and no self-ranking, no smoke, no mea culpas.

Ground the report before writing it

A sitrep that trusts the transcript reports intentions as achievements. The transcript records what was attempted; the repo records what happened.

• Check the working tree — git status, git diff --stat, and git log back to where the session started. This is what settles the Done/Open boundary for anything touching code.

• Re-read the artefacts the session claims to have produced where cheap — the file, the issue, the PR body. A file written three edits ago may not say what the session thinks it says.

• Say so if the context was compacted. One line, at the top: the earlier part of the session is a summary, so coverage before that point is partial. The reader needs to know which half of the report is first-hand.

Section 1: Done

One bullet per change that actually landed, children carrying the specifics. No IDs here — Done is not up for reply, and IDs on it are noise.

• Landed means verified, not attempted: the file is written, the test passed, the commit exists.
• Tag anything claimed but unchecked with unverified: rather than promoting or dropping it. A test that was written but never run is a real result and a real caveat; both belong on the line.
• Something discussed but not built is not Done — it is an idea, and belongs in Open.

Section 2: Open

One bullet per live item, each with a typed ID so the user can answer Q2 and leave the rest alone. This is the section that earns the sitrep — answering by reference is how the user will reply.

• I<n> — idea: raised, not adopted. Nobody is committed to it.
• D<n> — decision: a fork the work is standing at. Say what the options are and which way you lean, per the voting scale.
• Q<n> — question: needs the user's answer, and the work is blocked or guessing without it.

Per item, children say why it is still open and what would settle it — the missing fact, the answer needed, the experiment to run. Where an item blocks something in flight, say which.

• An ID's scope is the session, not the sitrep. chalk:voice requires a published ID to be stable; here that means Q2 stays Q2 across every sitrep in the session, even once Q1 is closed. Renumbering breaks every reference the user has already made, including in their own notes.

• A carried-over item is restated in full, never referenced by ID alone. A sitrep is most often read after a compaction or a break, which is exactly when the earlier reply that introduced Q2 is no longer on screen. Every live item gets its subject line in every sitrep that carries it.

• Newly-raised items take the next free number, never a recycled one.

• A closed item drops out silently. Don't keep a struck-through graveyard; if resolving it changed the state, that shows up in Done.

• Nothing open is a legitimate result. Say so in one line and stop. Manufacturing open questions to fill the section is the main way this skill goes wrong — it hands the user work that does not exist and buries the items that are real.

Section 3: tl;dr

Per chalk:voice, but at the bottom rather than the top, and not duplicated at the top. A terminal scrolls upward, so in a chat reply the last thing written is the first thing read. The placement is the only thing this overrides.

• Readable cold still binds, and it's the one voice rule chat otherwise relaxes. Someone who did not see the session should get where the work stands and what it is waiting on.
• Where there is an obvious next move, it is the last bullet. Where there isn't, don't invent one.

When the work has an issue or an open PR

Those are grounding sources, and they are where anything durable belongs. A sitrep is chat: it survives until the terminal is closed.

• Read them before writing. The issue description states the problem as it currently stands; the PR states what landed. A Done item that contradicts either is worth catching before you report it.

• Nothing in a sitrep should be material that isn't already in one of them, or on its way there. A sitrep is a view over durable artefacts, not a third place state lives. Where it turns out to be the only place something is written down, that's the finding — say so.

• Offer to write an Open item up where it would outlive the session. An unresolved Q goes to the Open questions section of whichever artefact owns it — the issue for the problem or the direction, the PR for the change that landed — via chalk:issue or chalk:pr. Offer, don't do it unasked: a sitrep is a read.

Cut hard

Length is the enemy here. A sitrep the user skims is worse than three bullets they read.

• Summarise at the altitude of the work, not the tool calls. "Reworked the retry path to back off on 429s" — not the six edits that got there.
• Drop dead ends unless the reason they failed constrains what comes next, in which case that constraint is the point and the attempt is the elaboration.
• Don't recap the user's own instructions back to them.