plain-voice
Skill0 starsChanged 37 days agoMITView on GitHub
Write deliverables the way a senior engineer types in a team channel: the decision first, plain declaratives, current state only, open points left open, misses in the headline, no rhetorical structure, no dashes as punctuation, no banned words, no tool attribution anywhere. Applies to messages, documents, change descriptions, review summaries and drafts in someone else's name. Triggers on: "draft", "write up", "humanise", "rewrite this", "tone", "voice", "summarise for", a message about to be posted, a commit or pull request description, a document for a team.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- cut-ticketsSkill
- decision-recordsSkill
- deep-modulesSkill
- evidenceSkill
- grill-planSkill
- plan-projectSkill
- review-changeSkill
- setup-conventionsSkill
- test-firstSkill
- thin-slicesSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 58
No headers in a message under about five hundred words.
- Distinctive: line 73
Write like that person types in a team channel: plain declaratives, what they saw, what they want, by when.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Plain voice
Text written for a reader who did not watch the work. The reader wants the decision, the
evidence under it, and nothing that performs. These rules apply to every deliverable; the
mechanical subset is enforced by agentic-sdlc lint-voice and the attribution rules by the
hook and the CI check where the plugin or the workflow is installed; elsewhere this text is the
rule. The decider is the role that approves and gives go-aheads: a role, not a person.
The rules
| Id | Rule | In practice |
| VOICE-1 | Lead with the decision | First line: the answer, the outcome, or the miss. Evidence underneath. Read the ask back and size the response to it. |
| VOICE-2 | Current state only | No narration of earlier versions ("rebuilt", "retargeted", "now split"), no version or branch labels in prose (links carry the sha). A repository document states the end state, never "today X, target Y". |
| VOICE-3 | No dashes as punctuation | No em dash, no spaced en dash. End the sentence or use a comma. |
| VOICE-4 | No rhetorical structure | No triads for rhythm, no counting framings ("two things", "three fixes"), no "that is why", no aphoristic last line, no throat clearing. |
| VOICE-5 | End when the content ends | No closing offer, no "let me know", no restating what was just said, no praise for the question. |
| VOICE-6 | Banned words | seamless, robust, best-in-class, leverage, comprehensive, world-class, delve, tapestry, testament, cutting-edge, game-changing. <!-- voice-lint: skip --> |
| VOICE-7 | No throat clearing | "It is worth noting", "note that", "importantly", "in summary": delete the preface, keep the sentence. |
| VOICE-8 | Evidence words carry evidence | "Live", "100%", "PASS", "confirmed", "resolved", "on track", "zero data loss" appear only with the evidence that earns them. "Green" is never a status: give the sha, the date and the lane, or the gate. See evidence (EVID-1). |
| VOICE-9 | Open points stay open | A reviewer's point, or one the decider has not settled: options, who decides, by when. Before a repository document or plan is pushed, list every normative sentence that settles a question and put it to the decider. |
| VOICE-10 | Misses are reported as misses | Scope cuts and skipped steps go in the headline. No apology language, no hedging, no softening. |
| VOICE-11 | Shared deliverables are technical only | No named individuals, no credit or blame, no reading of motives, no "ours" and "yours". Name the system and who picks it up. Restate a people finding as a system property. Never attribute a rejected idea to a person. |
| VOICE-12 | Verbatim words | The decider's words are used as given. An accepted draft is not polished further. |
| VOICE-13 | A draft promises nothing its signer did not say | Findings, a suggested order, what good looks like; the owner named in the plan carries the work. |
| ATTR-1 | No tool attribution in change text | No trailer naming a tool, no "Generated with" footer, no robot emoji beside one, in commits, pull requests, merge bodies, issues or release notes. The signer is the operator of record for the change. A role marker such as Operated-by: agent is not attribution and passes. Enforced by the hook and the CI check. |
| ATTR-2 | Strict mode | A repository may refuse any vendor mention in change text. Opt-in through .agentic-sdlc.json. |
Shapes that work
- One idea per sentence, about twenty words, with a verb. Short is not clipped: a sentence beats a label with a colon. Start a new sentence instead of joining clauses with a semicolon.
- Parallel items go in a list, one or two sentences per item, the first few words bold if the list is long. A single point stays in prose.
- Numbers and measurements go in a short table or on their own line, and only when they change what the reader does. Keep code out of prose: a file, function or flag is named only when the reader has to go there; commands and error text go in a fenced block.
- No headers in a message under about five hundred words; at most three above it.
- Sentence case in headings. Straight quotes. No decorative emoji.
Change descriptions
The first line is short, imperative and standalone: "Delete the FizzBuzz RPC". The body says what changes and why, with the context not visible in the diff, and names what it deliberately leaves out. Before a pull request exists, tell the decider in a few plain sentences what it does, why, and what it leaves out. No ticket keys, incident numbers, infrastructure identifiers, secret paths, partner URLs or colleagues' names in code, comments, tests or fixtures; they belong in the change title and description, and every reference to another change is a full link (TICKET-3, TICKET-4). thin-slices and cut-tickets point here for the text they produce.
Drafts in someone else's name
Write like that person types in a team channel: plain declaratives, what they saw, what they want, by when. Lead with the decision. End when the content ends. Never post, send, comment or save the draft: show it and stop.
The lint
agentic-sdlc lint-voice README.md docs reports the mechanical rules (VOICE-3 to VOICE-8) with
file and line; --fail-on fail fails the run on the hard ones and only warns on throat clearing
and evidence words. A line that must quote a banned word carries voice-lint: skip in an HTML
comment.
Before and after
Before:
It's worth noting that we've made significant progress — the migration is basically done and
the new service is robust. There are two things left: the cutover and the docs. That's why I'd
suggest we schedule the cutover for next week. Let me know if you have any questions!After:
The migration cutover is the next step; the docs follow it. Migration code merged on
2026-10-09 (a1b2c3d), replay tested against last week's production export (Measured:
0 mismatches over 41,000 rows). Cutover proposed for Tuesday 14 October; the on-call lead
decides by Friday.What changed: the decision first (VOICE-1), the evidence under it with its tag (VOICE-8), no dash, no counting framing, no causal flourish (VOICE-3, VOICE-4), no banned word, no closing offer (VOICE-6, VOICE-5), the open point named with who decides and by when (VOICE-9).
Companion skills
| Need | Skill |
| The tags behind the evidence words | evidence |
| Review threads and summaries in this voice | review-change |
| Tickets in this voice | cut-tickets |
Sources
The change-description example is Google's, from its engineering practices (CC BY 4.0). unslop (cursor/plugins, pstack, MIT) is the catalogue VOICE-3 to VOICE-7 coincide with.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

