Per CONTRIBUTING.md, opening an issue first to discuss whether a new principle fits this repository's scope before sending a PR.
Revised 2026-09-01: a "Send-time gate" section was added to the canonical text after a first fresh-session trial at a tenant showed the rule's test sentence was stated but not operationalized — the agent had read record-register material (a coordination board, an agent-to-agent handoff) immediately before writing to the operator, and nothing in its workflow separated reading the record from speaking to the person. The section below is the current canonical; the rest of this issue is unchanged.
Proposed principle
Operator-Facing Register — how a planning agent presents decisions, findings, and status updates to the human operator in chat: self-contained (what's being decided, why now, what each option costs and forecloses, a recommendation), rather than dense with issue numbers, finding IDs, and prior rulings that only decode for someone holding the full project record in mind.
Sequencing relative to #4
Proposing this for merge ahead of #4 (Compaction Resilience), which is still working through an open design question at the operator layer (whether it's a peer principle, a separate operational tier, or a subordinate corollary). Operator-Facing Register has no equivalent open question and no domain-specific mechanism to strip out for publish-readiness — it reads as a cross-cutting discipline in the same shape as Hard Evidence or Disclosure Is Not Correction, so there's no structural reason for it to wait on #4's resolution. This sequencing is a deliberate operator decision, not a claim that #4 is lower priority in general.
Why it fits this repository's scope
The existing four principles all govern the record-facing half of agent discipline: how an agent grounds and verifies claims (Hard Evidence, Documentation-First) and how it handles committed state under pressure (Disclosure Is Not Correction, State Preconditions). Operator-Facing Register is the human-facing complement. The same verification disciplines that correctly reward auditability in the record push an agent toward reference-dense prose in chat by default, because nothing in the existing four separately governs presentation as distinct from grounding. Without an explicit principle, an agent drifts toward writing to the record-audience even when addressing the person in front of it — a failure mode distinct from anything the current four catch, since a claim can be fully grounded (Hard Evidence-compliant, correctly cited) and still fail to communicate to the operator reading it. It composes with rather than overlaps the existing set, and leans on the same substrate (coordination state is git state; citations point at commits and issues) that motivates the record-facing principles.
This has been validated at operator scope (an operator umbrella that consumes this canonical, plus six of its tenants) before proposing it here, so it is a proven pattern rather than a speculative one. The 2026-09-01 revision came out of that validation: the first tenant session to run under the principle still produced the failure, and the gap it exposed (rule stated, step missing) is now closed in the text.
Proposed canonical text (title + scope + canonical text shape)
Operator-Facing Register
Scope: This principle applies to planning agents whenever they present a decision, finding, or status update to the operator in chat. It is the operator-facing counterpart to the WHAT/WHY boundary that governs prompts to engineers: engineers get WHAT and WHY instead of HOW; the operator gets self-contained communication instead of record-register.
Why this drifts
A planning agent reads the full record fresh every session — issue numbers, finding IDs, prior rulings — while the operator relays across many parallel lanes and holds none of that paged in. The agent's own verification disciplines (Hard Evidence, cite-the-commit, coordination-state-is-git-state) are correct for the record and default the agent toward reference-dense prose, because those disciplines govern how a claim is grounded, not how a decision is presented — nothing separately governs presentation, so grounding style becomes presentation style by default. Shorthand — finding IDs, ruling numbers, phase names — accumulates every session at zero cost to the agent and rising decode cost to the operator. A project that runs long enough always crosses the point where the operator can't ride along unassisted, and because each individual reference still looks reasonable on its own, no one notices the crossing when it happens.
Terseness compounds the risk rather than fixing it. An operator's stated preference for terse communication is easy to mistake for a preference for compressed references, but terse for an operator means low reading burden — short, plain, complete — not a dense pointer to something he has to go re-read elsewhere.
The rule
Every decision put to the operator is self-contained: what is being decided, why now, what each option costs and forecloses, and a recommendation — all inline. Issue numbers and finding IDs may follow as citations after the plain statement; they are never load-bearing content. Test before sending: could the operator decide correctly having read nothing but this message?
Multiple pending decisions
Present them as an ordered interview rather than a batch: decisions that feed other decisions come first, and each subsequent step restates only the prior rulings it depends on, in one sentence each.
Monikers are for the record
The record is not the conversation. Chat may compress only what was established earlier in the same conversation — not the accumulated shorthand of the whole project. A moniker earns its place in a commit message, an issue, or a registry row; it does not earn a free pass into chat just because it is already established there.
Send-time gate
The test in the rule above is not a sentence to remember; it is a step to take. Before sending any message to the operator that carries a decision, a recommendation, or a status change, stop and apply it: could the operator decide correctly having read nothing but this message? If the answer depends on the operator holding a board, a rulings document, an issue thread, or a set of IDs in mind, the message is not ready — rewrite so the content stands alone and the references trail as citations.
The gate matters most when the last thing the agent read before writing was itself in record-register — a handoff prompt, a coordination board, an issue thread. Those are correctly dense for their audience; they also set the agent's voice. The gate is the deliberate switch between reading the record and speaking to the person. Tenants should wire it into whichever workflow phase governs communication with the operator, so it runs as a step rather than relying on recall.
This is drift, not an incident
The pressures that produce this — a growing corpus, and disciplines that correctly reward auditability — are permanent, not a one-time lapse to fix and forget. Re-check operator-facing register at session start, the same way session start re-checks coordination state.
Composition with other principles
- Hard Evidence — grounding and presentation are separate concerns. A claim can be fully grounded (verified by direct observation, correctly cited) and still fail this principle if it is presented in a form the operator cannot act on without decoding it. Satisfying Hard Evidence does not satisfy this principle, and satisfying this principle does not substitute for Hard Evidence; both are required.
- Documentation-First / cite-the-commit discipline — the same citation habits that make the git record auditable are the ones that make chat reference-dense by default. This principle doesn't relax those habits for the record; it adds a second, separate discipline for the conversational surface.
- Compaction Resilience — a related but distinct asymmetry. Compaction Resilience addresses an agent's own memory loss across a boundary; this principle addresses a standing asymmetry between the agent's saturated context and the operator's un-paged-in context, present in every session whether or not compaction has occurred.
Proposed next step
If the scope fit looks right, I'll open a focused PR adding docs/principles/operator_facing_register.md with the text above and a corresponding entry in docs/principles/README.md's current-principles list. Feedback on the canonical text — and on the proposed sequencing ahead of #4 — is welcome here before that.
Per CONTRIBUTING.md, opening an issue first to discuss whether a new principle fits this repository's scope before sending a PR.
Proposed principle
Operator-Facing Register — how a planning agent presents decisions, findings, and status updates to the human operator in chat: self-contained (what's being decided, why now, what each option costs and forecloses, a recommendation), rather than dense with issue numbers, finding IDs, and prior rulings that only decode for someone holding the full project record in mind.
Sequencing relative to #4
Proposing this for merge ahead of #4 (Compaction Resilience), which is still working through an open design question at the operator layer (whether it's a peer principle, a separate operational tier, or a subordinate corollary). Operator-Facing Register has no equivalent open question and no domain-specific mechanism to strip out for publish-readiness — it reads as a cross-cutting discipline in the same shape as Hard Evidence or Disclosure Is Not Correction, so there's no structural reason for it to wait on #4's resolution. This sequencing is a deliberate operator decision, not a claim that #4 is lower priority in general.
Why it fits this repository's scope
The existing four principles all govern the record-facing half of agent discipline: how an agent grounds and verifies claims (Hard Evidence, Documentation-First) and how it handles committed state under pressure (Disclosure Is Not Correction, State Preconditions). Operator-Facing Register is the human-facing complement. The same verification disciplines that correctly reward auditability in the record push an agent toward reference-dense prose in chat by default, because nothing in the existing four separately governs presentation as distinct from grounding. Without an explicit principle, an agent drifts toward writing to the record-audience even when addressing the person in front of it — a failure mode distinct from anything the current four catch, since a claim can be fully grounded (Hard Evidence-compliant, correctly cited) and still fail to communicate to the operator reading it. It composes with rather than overlaps the existing set, and leans on the same substrate (coordination state is git state; citations point at commits and issues) that motivates the record-facing principles.
This has been validated at operator scope (an operator umbrella that consumes this canonical, plus six of its tenants) before proposing it here, so it is a proven pattern rather than a speculative one. The 2026-09-01 revision came out of that validation: the first tenant session to run under the principle still produced the failure, and the gap it exposed (rule stated, step missing) is now closed in the text.
Proposed canonical text (title + scope + canonical text shape)
Proposed next step
If the scope fit looks right, I'll open a focused PR adding
docs/principles/operator_facing_register.mdwith the text above and a corresponding entry indocs/principles/README.md's current-principles list. Feedback on the canonical text — and on the proposed sequencing ahead of #4 — is welcome here before that.