Notes: the communication rules refactor

Review of the first-pass refactor and what the rewrite did with it. Written 2026-08-22.

Issue: #835 splitting the communication rule. Live source being replaced: .agents/rules/project/communication-voice.md

What is in this folder?

File	What it is	State
notes.md	This file	Live

Both rules shipped on 2026-08-22. The docs rule is at .agents/rules/project/writing-into-documents.md, and the voice rewrite is at .agents/rules/project/communication-voice.md. Its proposal copy was deleted rather than left here to drift; this file stays as the record of what changed and why.

What did the first-pass refactor get right?

• Question headings. Better retrieval shape than prose sections, and it matches the convention being set in skill-creation.md. Kept, and used as the only heading form.
• Naming the personal overlay and stating precedence. The live rule never mentions my-voice.md at all, so the relationship between the team contract and one person's overlay lived nowhere. Kept, expanded into a three-row precedence table that also covers a skill's own format spec.
• Neutral party framing. The live rule says "she" and "her" throughout, which is right for an output style and wrong for a file four tools load for every contributor. Kept, and the whole rewrite is written for "the reader".
• "Not everyone here is technically savvy." Kept, joined to the define-your-terms rule.
• Splitting Questions from Updates. An update is not an ask, and the live rule jammed both into one table. Kept as two tables with the same column shape.

Why did it get split into two files?

The live rule does three jobs under one name: how to talk, what shape a message takes, and how to write into a document. The third one fires when authoring a spec or a PR body, not when talking to anyone, and it never belonged in a voice rule.

Operator ruling 2026-08-22: split into two. Tone and message format stay together in communication-voice, because tone rarely fires without format. Document authoring becomes its own rule.

Why was the tone section rewritten from scratch?

The live rule tests for warmth like this:

Tone needs a test, because every rule around it is checkable and this one is not. "Is this under a screen?" can be answered. "Is this warm?" cannot, so compression wins every exchange unless you deliberately check. The test: reread what you wrote, and if a dashboard could have produced it, rewrite it.

Operator finding, 2026-08-22: that paragraph is the reason the voice never held. Three failures in one:

1. It concedes in its own first sentence. Telling a reader which rule is the weak one is permission, not a warning. It hands over the excuse and then asks them to catch themselves using it.
2. It makes warmth a post-hoc audit. By the time you are rereading, the message is already a briefing, and rewriting for tone at that point means bolting adjectives onto a table. Tone is set before the first sentence or it does not happen.
3. "Not a dashboard" is a floor, not a target. Clear it and you have achieved not sounding like a robot. Nothing in it asks you to sound like a person. Worse, it names the symptoms (bolded labels, fragments, nouns), so the output avoids those specific tells while staying a status report underneath.

Replaced with a positive target ("write like you are explaining something to a friend who is sharp, busy, and who you actually like talking to"), a timing instruction (decide tone before the first sentence), and a worked before/after pair, which does more than any amount of describing.

Why is the whole file phrased as invitations now?

Same finding, applied consistently. The first pass and the live rule are both roughly ninety percent prohibitions: never, don't, cut, avoid, skip. A rule file written as restrictions produces an agent that writes defensively, and defensive writing is exactly what warmth is not.

Every rule keeps its substance. The framing flips to what a good message does. "Do not add a why-it-matters column" becomes "three columns, each with one job". "Never bury an ask in prose" becomes "put every ask in the table". The genuine tripwires are pulled out into a short closing section of three, with a line saying everything above it is guidance rather than a checklist.

What was restored from the live rule?

The first pass cut the file roughly in half. Most of what it cut was substance, so it went back.

Restored	What it prevents
Status mode vs explanation mode	A question the reader asked getting compressed into a table
One screen for a status, with the reason	A status longer than the pane cannot be finished, and there is no scrollback
Actual issue titles, not bare numbers	A bare number makes the reader hold a number-to-meaning map. The first pass covered bare LINKS, which is a different rule
Link every document you name	A named doc with no link sends the reader digging
Restate a carried-over ask in full	A pointer to an earlier message points at nothing on a phone
Recommendation first, then a matrix	The first pass had no decision format at all, which permits a flat list with no opinion
Use the tappable question tool	Cheapest possible form for a real choice
Say it plainly once verified
Report outcomes faithfully
Only actively-worked rows in the ask table	Operator rule, 2026-08-19. Stops the table becoming a wish list
Push notification when work wraps	Terminal output reaches nobody who is away from the terminal
Humor is welcome	Reaffirmed 2026-08-19. Folded into the tone section as part of the target rather than as a defensive counterweight

What was dropped, and why?

• The dashboard test. See the tone section above. It was in the live rule and in the first draft of this rewrite, and it is the single thing most responsible for the drift it was meant to catch.
• The "why it matters" column on the Questions and Updates tables. Each column has one job and none of them is explaining yourself. A column named "why it matters" is a standing invitation for exactly the rationale that gets called a defect.
• The rubber duck instruction. In a file read at write time, "explain your reasoning to yourself before communicating" either does nothing or nudges toward narrating reasoning, which fights answering what was asked.
• The name origins bullet, from this file only. Not a loss: naming-origins.md has been its own rule the whole time, and the voice rule was carrying a duplicate.

What changed after it shipped?

Questions and Updates gained a "Where it lives" column. Operator finding, 2026-08-22, from a live status message: the row asked whether "about 23 lines" should stay in the shared rule, and there was no way to tell which file that line was in without asking. The middle column says what a thing IS, which is not the same as where to go look at it.

The column holds a link, not a description. Four columns is now the standard shape for both tables, with a fifth reserved for a specific decision that needs a risk, a deadline, or a cost.

Worth noting the failure mode: the rule already carried the right test ("could the reader act on the row without asking what it refers to?") and the row still failed it. A test does not fire on its own.

What routes to my-voice instead?

Less than expected. The personal half already lives in ~/.agents/context/lantern_app/my-voice.md (how she wants to be talked to, how she talks, the typo dictionary, approvals are scoped to one object). Nothing needed to move out of the rule; the rule needed to stop being written in the second person singular, which the rewrite does.

One line is arguably personal and was kept in the project rule: "about 23 lines, because a terminal pane is roughly that". Every agent in this repo writes into the same terminal, which argues for shared, but the number is one person's setup. Worth a ruling either way.

my-voice.md also carries its own diagnosis of why the voice decayed, built on the same checkable-beats-uncheckable argument this rewrite retired. It wants the same pass.

What did the operator flag on the docs rule?

Two notes, left on the draft 2026-08-22, both addressed before it landed.

1. docs/planning/ is being deprecated, and the replacement needs to be scalable and not drift. The draft cited that directory as a home for rationale, so it would have broken the day the directory moved. Fixed by citing only the homes that are not going anywhere: the issue, the PR body, git history, and whichever spec recorded the decision. Whatever replaces docs/planning/ slots in without the rule needing an edit.

2. This is a good overarching summary, but creating a doc is per-type: a spec is not a runbook. Correct, and it is already planning.md item 1, the four document-type skills modelled on test-plan. So the rule scoped itself hard to the layer UNDER every document type and stopped covering creation at all. Its "Where does a new document go?" section was cut, since non-negotiable rule 5 and key-conventions already cover updating before creating.

What has to happen before these go live?

Not done here. This folder is a proposal.

1. Move both files to .agents/rules/project/. Nothing under docs/ is read by the sync.
2. Add AGENTS.md markers for the new rule, or npm run sync:agents throws: <!-- AGENTS-SYNC:START writing-into-documents --> and the matching END, with a hand-authored heading above them.
3. Run npm run sync:agents and confirm it regenerates the Copilot instructions file, the Cursor mdc, the Operator Voice output style, and both AGENTS.md blocks.
4. Check outputStyle is still set to Operator Voice in .claude/settings.json. Generating a style never selects it, which is how the style sat inert from creation until 2026-07-26.

What is still open?

writing-into-documents reaches Claude only through AGENTS.md. It is set to agentsMd: full, so its body loads on every turn of every session, including the sessions that never write a document. The alternative is the output style, and there is one slot: two rules setting claudeOutputStyle: Operator Voice would generate the same filename and the second would overwrite the first. Options are to accept the AGENTS.md cost (the body is about 41 lines), to make the sync support multiple rules per style, or to demote it to a skill and lose the always-on guarantee.

Question-headers-only is now a stated convention but nothing enforces it. The other 11 rules do not follow it. If it is going into the rule and skill writing configs, it wants either a lint check or an explicit "new files only" note, or the two styles sit side by side indefinitely.

The invitation framing has the same problem. It is the more important of the two conventions and it is even harder to check than the heading form. Nothing currently stops the next edit from adding a "never do X" bullet and starting the slide back.