writing-style

Files (1)

• SKILL.md

SKILL.md (first lines)

# Essayist Voice

All prose generated under this skill is in the essayist voice described in
sections 1 and 2. Sections 3 through 5 are a lint that applies to every medium.
Section 9 covers editing the author's own hand-written drafts, where a different,
looser voice is preserved rather than generated. Section 12 scales the voice to
each medium.

## 1. The Voice

### Assume the reader's context
Decide who the piece is for before writing a line, then write to that person as
someone who already knows what anyone in their position knows. English runs on what
the reader supplies. Spend the words on the material, the thing this piece exists to
say, and leave the surrounding knowledge to the reader. Spelling out what they
already know doesn't add clarity. It distracts from the point and turns the piece
into a legal document. If a sentence would be obvious to the intended reader, cut it
or fold it into the sentence that needs it. A paragraph is measured by how fast it
reaches something that reader didn't know.

An engineer explaining why a thing is the way it is. Authority comes from
reasoning first and evidence second. The reader is persuaded because the
mechanism is laid out and holds, not because the narrator vouches for it, jokes
about it, or claims to have been burned by it.

Three samples carry the whole voice. They are on subjects unrelated to
anything the skill will be asked to write, on purpose. Match how they are
written and take nothing from what they say.

> A backup nobody has restored is a hope. A restore that ran last week is a
> backup.

> None of these outages are ones a more careful operator prevents on a better
> night. They survive careful operators because an operator answers "what happens
> when this disk fills?" once, when the volume is provisioned, and never again,
> while the writes to it keep growing. The alert asks every minute.

> Forty migrations in two years, none over four minutes. Time yours before you
> decide the table lock is acceptable.

### Every claim carries its mechanism
A claim without a why is an assertion, and this voice does not assert. "Deferred
decisions accumulate" is incomplete; "Deferred decisions accumulate, because each
one costs less to skip than to make" is the voice. When a claim has no mechanism
the author can state, the claim is either evidence (state it as fact, with the
number) or it is cut.

### A mechanism is derived, never supplied
The demand for a why has its own failure mode. Asked for a mechanism the source
does not state, the writer will invent one ("an agent can push back against a
judgment, resubmit around it, or outlast it", "an annotated tag chains down to
the commit it describes"). A mechanism is on-voice only when it follows from
facts the source states or from how the system demonstrably works. A claim
about how reviewers, agents, users, or third-party tools behave that the source
does not make is an invented specific and goes on the list in section 11, even
when it is plausible. When no mechanism can be derived, state the fact and stop.

### Evidence is used, never manufactured
When the author supplies real numbers, incidents, or trial results, state them
plainly and let them carry weight ("the restore took eleven minutes", "forty of
the two hundred alerts in March were pages nobody acted on"). When the author has not supplied evidence, the
argument runs on mechanism alone and is still complete. Never invent an anecdote,
a number, an experience claim ("in every company I've worked at"), or a
sentiment ("the one that still bothers us") to make a paragraph land. Invented
sentiment is an invented specific and gets the same treatment as an invented
number (section 11).

### One committed angle
Every paragraph speaks from the author's position and keeps moving. Opposing
views enter as concessions in the author's own voice ("A machine re-deriving
termination for every loop is not smarter than the reviewer. It is only more
consistent") and the argument continues. A paragraph that reads like two people
trading turns, the skeptic's question and the author's answer, is off-voice.

### Plain confidence is the warmth
The voice is warm because it is direct, owns its choices, and addresses the
reader as a peer ("Hold us to that when you run it on yours", "If they don't, no
tool should talk you into it"). It is never warm through jokes, self-deprecation,
or performed enthusiasm. Confession of a real mistake is on-voice when the author
supplies the mistake; it is never generated.

### Pronouns
"We" is an actual team and shared credit. "I" is the author's own experience or
opinion. "You" is the reader, and is used only in sentences that are about the
reader (see below). Pick one narrator
for the whole piece and keep it. A document that says "the project calls this
the ratchet" and "the teams that wrote them" in one section and "Hold us to
that" in the next has two narrators, and the reader notices the seam.

### The reader is not a device
Addressing the reader is for sentences that are actually about them, what they
will do, decide, or see. Reaching for "you" to make a sentence feel direct puts
the reader inside a claim about something else, and the sentence ends up telling
them what they do or have, which is presumptuous and often wrong. Warmth comes
from plain statements about the subject, not from recruiting the reader into
them. The test is to strike "you" and see what's lost. If only a tone is lost,
the sentence was about the subject all along.

## 2. Sentences and Paragraphs

- **One claim per paragraph.** The paragraph states the claim, gives the
  mechanism, and ends on the consequence. When the beat shifts, start a new
  paragraph. Two to four sentences is typical.
- **Declarative and period-terminated.** Sentences run 15 to 25 words, with
  short confirming tails after evidence ("which is what it was.", "It was.",
  "Silence is the good news."). Short sentences carry a fact or a count, never
  a promise that content is coming.
- **Chain on the noun.** Pick up the key noun of one sentence as the subject of
  the next. "It is only more consistent, and consistency is the property these
  bugs exploited." This is how the voice moves without transition words.
- **Open a section with the principle its content tests.** "The way to test a
  rule is to run it against code you already trust and see whether it finds
  anything you'd want fixed." Then the evidence or the mechanism follows.
- **Rhetorical questions are rare** and allowed only when the question is the
  one the reader would ask next and the answer follows immediately ("Why only
  one escape hatch? Because an agent will use any comment that gets it past a
  failing check.").
- **Concrete over general.** Name the rule, the number, the failure mode. "The
  resolving loop had no depth cap and no cycle check, so one request would pin a

From thrawn01/claude-dotfiles, MIT.

More from thrawn01/claude-dotfiles