diff --git a/docs/SESSION-MAIL.md b/docs/SESSION-MAIL.md index da71478f..ffe81a6f 100644 --- a/docs/SESSION-MAIL.md +++ b/docs/SESSION-MAIL.md @@ -665,6 +665,26 @@ re-argue that number. --- +## Replying: one line, and mail arriving is not a reason to produce output + +**The rule: `: `, 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 diff --git a/scripts/hooks/mail-drain.ps1 b/scripts/hooks/mail-drain.ps1 index 25d45772..a414bcbe 100644 --- a/scripts/hooks/mail-drain.ps1 +++ b/scripts/hooks/mail-drain.ps1 @@ -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