Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/SESSION-MAIL.md
Original file line number Diff line number Diff line change
Expand Up @@ -665,6 +665,26 @@ re-argue that number.

---

## Replying: one line, and mail arriving is not a reason to produce output

**The rule: `<who mailed you>: <minimal reply>`, on ONE line.** Examples --
`steward: pool warning, noted`, `builder-2bee12: no action`, `lander: their retraction, nothing owed`.

**Why it is a rule and not a style preference.** The drain hook **blocks the Stop**, so every delivery
re-invokes the session and forces a turn. That turn is billed with the **entire conversation context
re-sent**, whether it says one word or six paragraphs. On 2026-08-18 a paused session with nothing to
do produced roughly a dozen consecutive turns of multi-paragraph peer-traffic digests -- none
requested, each one a full-context charge, while the owner was actively watching pool burn.

**Do not summarise or relay peer traffic to the owner.** Peers correcting each other is the channel
working; it is not news. Surface a message only when it needs the **owner's** decision -- a merge, an
approval, an outward-facing action -- and then say only that, in one line.

**This rule is printed by the hook itself**, in the footer of every delivery, for the reason a peer
seat established the same day about announce-before-fan-out: a norm with zero observable consequence
for skipping it gets skipped. The doc is the record; the footer is what reaches the moment the reply
is composed.

## Related

- [WORKTREES.md](WORKTREES.md) -- parallel sessions, the SessionStart coordination context, and the
Expand Down
9 changes: 9 additions & 0 deletions scripts/hooks/mail-drain.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -1101,6 +1101,15 @@ try {
}
$lines += "[mefor-mail] end of delivered mail. Every line above beginning ' | ' was sender-supplied;"
$lines += "every other line was written by this hook."
# The reply-length rule, printed HERE rather than left to docs/SESSION-MAIL.md alone. This hook
# BLOCKS the Stop, so every delivery forces a billable turn whose full context is re-sent. A
# session with nothing to do was writing multi-paragraph digests of peer traffic the owner never
# asked for, once per drain. A norm in a doc nobody re-reads does not reach the moment of
# decision; this line is in context exactly when the reply is composed.
$lines += "REPLYING: keep it to ONE LINE -- who mailed you, and the minimal reply. Example:"
$lines += " 'steward: pool warning, noted' or 'builder-2bee12: no action'. Do NOT summarise,"
$lines += " digest, or relay peer messages to the owner unless a message needs THEIR decision,"
$lines += " and then say only that. Mail arriving is not a reason to produce output."
# Rebuilt here so the truncated/withheld counts reflect what was actually rendered above.
$counterLines[0] = "[mefor-mail] box: $($delivered.Count) shown, $deferred deferred (caps), $truncated truncated, $withheld withheld,"
$lines += $counterLines
Expand Down
Loading