Write Better

---
name: write-better
description: Writing norms and an enforced revision pass for when Claude is the primary drafter. Fires mechanically, not by judgment: load and run this skill before (a) any Write or Edit that adds a paragraph or more of prose to a vault file — deliverables, research summaries, project logs, notebook entries, web copy, synthesis docs — (b) delivering copy in chat that Ida will use verbatim (page copy, descriptions, titles), at any length, or (c) authoring an Artifact or standalone HTML/shareable deliverable Ida will send or publish (a file written to scratchpad rather than the vault still fires the rule). Does NOT fire for: editing Ida's own words (that's /cleanup), code or YAML-only edits, one-line factual additions, or conversational replies. NOT for Ida's byline writing (essays and posts under her name), which she drafts herself. This skill always rewrites the wording; for mechanical-only fixes with the words left intact, use /cleanup. Run the revision pass and end with its revision note before delivering; don't offer.
---

# Write Better

Norms for when Claude is doing the heavy lift on writing. This covers client-facing materials, formatted dictation, comms copy, research summaries, descriptions, and anything where Claude drafts and Ida sends or lightly edits.

This is NOT for Ida's original writing (thought pieces, essays, posts). That has its own norms in the Content Creation Pipeline.

**This skill always rewrites the words.** Changing the wording is the point, not a risk to manage. When the input is existing text to improve — Claude's own draft or another model's output — write-better rebuilds it; preserving the wording is never the write-better mode. If you want only mechanical fixes (typos, punctuation, speech-to-text artifacts) with the wording left intact, that is `/cleanup`, not this skill. There is no light-touch version of write-better.

## Why These Norms Exist

LLM training produces writing that is fluent, structured, and confident — and also generic, over-polished, and full of identifiable patterns. These patterns are baked into the weights as "good writing" but are not good writing. They flatten voice, patronize readers, impose narrative where none is needed, and betray machine authorship to anyone paying attention. This skill exists to catch and override those defaults.

**The operative test (Ida, 2026-07-20, from the deep-reckoning writing standard).** Under every tell below sits one question: does a construction *reduce or reproduce the reader's decoding load?* The tells always add load, however well they read, which is why fluency is the thing to distrust rather than trust. This reframes each tell from a small deduction into a category error: a document written to be understood that adds decoding cost works against its own reason to exist. The same test runs at the passage level: a passage whose information the intended reader already holds adds decoding cost and nothing else, so cut it however well it reads. Dense prose is Ida's weakest channel, so the cost lands doubly. Say the complicated thing simply; never make it simpler than it is.

## When to Use

- **The firing rule is mechanical.** Run this skill's revision pass before (a) any Write or Edit adding a paragraph or more of prose to a vault file — including project logs and notebook entries — (b) delivering verbatim-use copy in chat, at any length, or (c) authoring an Artifact or any standalone HTML/shareable deliverable Ida will send or publish. File location does not exempt it: a page written to scratchpad rather than the vault still fires the rule.
- Does not fire for: Ida's own words (that's /cleanup), her byline writing, code or YAML-only edits, one-line factual additions, conversational replies.
- Ida points at something Claude drafted and asks for improvement → back through this skill. If the words are Ida's, only /cleanup touches them.
- Load and run, don't offer. Never ask first, never deliver the first draft.

When invoked, load `references/llm-tells.md` and `references/construction.md`, and apply all norms below.

## Mode: light or heavy

Decide this before writing; the choice is itself skip-prone, so make it first.

- **Heavy** — a standalone HTML/shareable deliverable, anything someone other than Ida reads, or 300+ words of new prose in a deliverable file. Full pass, and **Step 0: write the seed first, then generate from it** (the seed is step 1's claim checklist written before the draft, not after). Save it where the seed-gate hook looks for it (see How It Fires on the published page); give it three headings — **Substance** (facts from source with members NAMED: the actual fibers, the five care actions, the real number, never a category noun), **Reader** (who reads it, what they leave able to do), **Standard** (the register target with one pasted exemplar). A large `.html` write is denied until the seed exists; a large `.md` deliverable gets a reminder.
  For a long explanatory deliverable (roughly 1,500 words of prose or more), add a cold read by a stronger model before shipping, briefed to flag every passage a first-time reader would have to read twice.
- **Light** — verbatim chat copy, log and notebook entries, short vault additions, single paragraphs, ordinary project-file edits. The fast pass only: sentence and stress tests, the scan, a quick read of the named checks. No seed file, no fielded note.

## Assess Before Writing

- **Is the source material clear enough to draft from?** If there's ambiguity about audience, tone, purpose, or key content decisions, ask before writing.
- **Is there existing writing in this context to match?** If adding to or following up on something Ida already wrote, read it first and match the register.
- **Who is this for?** Match the register to the relationship and context. A team note is warm and invitational. Feedback to a client is collegial and direct. A proposal is precise and structured. Match the level of detail to the reader's expertise as well. A technical reader wants the mechanism, and hand-holding only slows them. A lay reader needs the terms unpacked. Wrong depth misfires like wrong register.
- **If working from dictation:** preserve Ida's language and framing. Tighten (cut filler, clean speech artifacts), but don't paraphrase or reinterpret. When a phrase is Ida's, keep it.
- **If synthesizing from existing notes or research:** the source material is the ceiling, not the floor. Preserve exact titles, exact attributions, exact language. Organize and compress — don't embellish, reframe, or editorialize.
- **Heavy mode starts at the seed (Step 0, above), not the draft.** A weak first draft is a generation problem before a revision one: writing from the topic produces the gist, and the gist is abstract. When the draft still comes out abstract, the seed was thin; thicken the seed rather than tuning the sentences.

## Writing Norms

### Sentences and Words

**Active voice.** Passive hides the actor and flattens the writing.

**Concrete over abstract — name the members.** Name the thing, not the category. When a category noun stands in for members that are short and nameable, name them: "washing, bleaching, drying, ironing, and dry cleaning," not "each thing you can do to a garment." The "thing you can/do to X" phrase is the tell and the scan flags it; a bare category noun ("the methods") the scan can't see, so that one is yours to catch.

**Verbs must be physically true.** Picture the verb happening to its subject. If it can't happen to that thing, use the verb that names what actually happens. Two forms:
- An impossible action on a physical thing: a pound "holds" yarn, hanks "fill" a pound, a weight "contains" length. Instead: "a pound of this yarn is shorter."
- A physical verb borrowed for something abstract: a finding "lands," a number "sits at," a pattern "surfaces," a plan "carries" risk. Instead: the finding "shows," the number "is," the pattern "appears," the plan "risks."

Read for this in every draft. The scan can't detect it.

**Read numbers and notation out literally.** Every figure or notation the reader has to interpret gets one sentence saying what it means in the world: "40 denier: 9,000 metres of this yarn weighs 40 grams," "40/2: two size-40 strands twisted together." Financial and technical figures need the same treatment.

**Cut throat-clearing.** No sentences that announce what you're about to say. Get to the verb.

**Vary sentence length.** Short sentences for weight. Longer sentences to develop and breathe.

**Earn every word.** If a sentence could lose a word without losing meaning, lose the word. If a paragraph could lose a sentence, lose the sentence.

**Don't over-structure.** Not everything needs a header, a bullet list, or parallel construction. Let the content determine the form.

**Complete, grounded sentences over gestures.** A fragment used for punch ("Not just backing it, but using it.") gestures at a point without landing it. Write the full sentence that states the claim.

**No appositive tail.** A sentence that ends on "[clause], [short appositive or -ed/-ing phrase]" leans on cadence the way LLM prose does: "one duty, exercised in ink," "the ISO set, close but not identical," "gray dashes, no green," "the safe way, full stop." Rewrite the tail into a full clause, or cut it. The mechanical scan catches three literal forms of this; the shape is general, so read for the rest.

**Convincing, not persuasive.** Convincing is grounded — the claim earns belief because it's specific and sourced. Persuasive is rhetorical lift: cadence, contrast, and punch standing in for substance (internet-marketing slop). When a point can be grounded in the source material, state the grounded version. A gesture ("actually using it and saying what for") is weaker than the finding underneath it ("the strongest predictor of adoption is whether leaders use it themselves"). Reach for the evidence, not the cadence.

**Punctuation:** Prefer periods and commas. Colons for lists or elaboration. Semicolons sparingly. Minimize em dashes.

*Scan for:* any word or phrase from `references/llm-tells.md`. Em dashes. Tricolon lists. Sentences starting with "This" referring vaguely to the previous sentence. Sentence fragments used as rhetorical gestures (esp. "Not just X, but Y").

### Structure

**Let the content's shape set the form.** Don't default to a bullet list because there are several points — prose carries reasoning better; lists are for genuinely parallel items. If they're not parallel, it's not a list.

**Vary the shape of items.** When every item is the same length and rhythm, it reads as a template and flattens emphasis. The important one can run long; a minor one can be a clause.

**Lead with substance.** Cut orienting preamble if the first real point can open. Setup sentences are usually deletable.

**Cut what the reader already knows.** A passage that establishes or justifies something the intended reader already holds adds no information, however true it is. Cut the background they already have and the case for why the subject matters. Open on what they don't have.

**Don't impose symmetry.** Real content is asymmetric. The strongest point earns more room; don't pad the others to match.

**Order by what matters,** not by the order the source happened to present things.

**Don't over-section.** A header every few lines fragments more than it organizes.

*Scan for:* lists whose items are uniform in length and construction. Setup-before-substance openings. Passages establishing context the intended reader already has. Padding added for symmetry. A bullet list where prose would carry the reasoning better.

### Register

**Write like a competent person talking to competent people.** Clear, direct, unshowy. The reader notices what's being said, not how.

**Write to people, not about situations.** "Here's what you'll be doing" instead of "The activities will consist of."

**Warmth through specificity, not adjectives.** If the warmth isn't grounded in something specific, cut it.

**No salesmanship.** Don't inflate, don't pitch, don't add urgency that isn't there. State what's true.

**No diagnostic register.** Don't name what's broken, warn about consequences, or prescribe what needs to happen. Present what was heard, not what's wrong. "Just because people are using the same words doesn't mean they're working towards the same ends" (observational) — not "If the retreat lands on only one framing, people will feel unheard" (diagnostic).

**No contrastive expertise framing.** Don't frame Ida's expertise against a foil ("most facilitation treats all groups the same"). Frame from inside the expertise, not against an imagined opponent. This instinct is deep and persistent.

*Scan for:* sweeping comparisons or uniqueness claims. Diagnostic language (prescribing, warning). Expertise framed against a foil. Overly balanced paragraph structures.

### Presenting Information, Research, and Findings

**Describe what the information shows, then stop.** "Three of four interviewees named role clarity unprompted" is evidence. "Role clarity emerged as a dominant theme" is interpretation dressed as evidence.

**Present information at the same altitude it was found.** A data point is a data point. A pattern is a pattern. A speculation is a speculation. Don't promote things up the ladder.

**No superlatives or intensity markers.** Drop "remarkably," "strikingly," "notably," "unprecedented."

**No dramatic framing.** "Income generation outside institutional scaffolding has no precedent in the earnings history" describes. "Every single dollar came from institutional employment" amplifies.

**No narrative arc imposed on facts.** Lay the information flat so the reader can see their own patterns in it.

**When multiple interpretations exist, hold them open.** "This could mean X or Y" is more useful than picking one.

**Questions over verdicts.** "Worth asking whether this pattern holds under pressure" — not "this is a red flag." Only render a verdict when Ida specifically asks for one.

*Scan for:* interpretive gloss — any sentence drawing a conclusion not in the source. If you can't point to the source that says it, cut it. Rhetorical scaffolding — sentences that anticipate and defuse concerns the reader hasn't raised. Information promoted above its actual altitude. Fabricated titles or citations — never generate a title from memory; retrieve it from the source.

### Explaining Something New

When the reader is meeting the material for the first time (study materials, how-tos, setup docs, client explainers), three more checks apply. They come from the yarn-numbering study guide (2026-10-05), where the sentences were grammatical and the reader still got lost.

**Sort the terms by kind before drafting.** List every term the reader may not know and name what kind of thing each is: a unit, a method, a result, a category, a notation. Then flag every word that does more than one job. "Denier" names a method and also the unit of its answer; "count" meant three different things on one page. Give the reader the sorted list up front, and wherever a double-duty word switches jobs, say which job it is doing. A definition says what a word means, but the reader also needs to know what kind of thing it is: Ida's question was whether denier measured width or length.

**Define before use, in the order the reader meets things.** Walk the piece in the reader's order, with diagrams, labels, buttons, and captions included, and confirm that no term appears before the sentence that defines it. In the yarn guide, the first diagram used "denier" and "hank" in its labels before any text defined them.

**Give every rule its cause.** State the chain that produces a rule along with the rule: "a heavier yarn puts more grams on the scale, so the number goes up." A reader who has the cause can rebuild the rule; a reader who has only the rule has to memorise it.

### Headings

**State the content, not a reaction to it.** Headers should tell you what the section contains without reading it.

*Scan for:* vague pronouns ("it," "this," "that") standing in for the actual subject. Teasing or dramatic headers that build intrigue instead of conveying content.

**Heading a section with its subject, as a noun phrase, is the default.** A reader skimming the headings alone should learn what the document covers. Five failures Claude's drafts keep producing:

- **A count in place of names.** "Two figures" says how many; name them.
- **A question in place of the claim or the measure.** "Will the money last," "Why each is a single number." Name the measure, or state the answer the section gives.
- **The source in place of the content.** "Survey results" says where the numbers came from, not what they are.
- **A metaphor verb.** "How the budget is built" dresses up "reasoning."
- **A pronoun.** "Keeping it current."

**Worked example: a heading rewrite** (invented for the published copy, following the pattern of a real rewrite Ida made of Claude's headings on a planning document, 2026-10-05). The document is a neighborhood tool library's annual report. Claude's version first, then the rewrite:

- "Membership" → "Membership and Loan Figures"
- "Two numbers" → "Active Members and Monthly Loans"
- "How the budget is built" → "Repair Budget Reasoning"
- "Why each tool has one fee" → "Single Late Fee Averages Loan Length"
- "Will the fund last" → "Probability the Repair Fund Covers the Year"
- "Survey results" → "Members' Ratings of Tool Condition"
- "What's Not Captured in the Count" → "Not Accounted for in the Loan Count"
- "Keeping it current" → "Keeping the Inventory Records Current"

The rewritten headings are longer and plainer: each names its subject in full, and none asks a question or reaches for a figure of speech. "How to log a returned tool" stays as written, because that section is a procedure, so how-to headings stay for steps.

## Revise Before Delivering

The norms above describe the target. They don't enforce themselves: generating text and auditing text are different acts, and a fluent first draft embeds the tells even when the norms are known. Never deliver the first draft. Run every step below and end with the revision note, so a skipped pass is visible. The pass constructs as well as catches: cutting a tell leaves a hole the same trained rhythm refills, and step 2 is the method that fills it properly.

1. **Structure first — and rewrite from source if the draft is weak.** Before sentence work, check the shape: right form (would prose beat this list, or vice versa — and where the content is structural or relational, would a diagram or table beat prose? Dense prose is Ida's weakest channel, spatial her strongest), strongest point up front, nothing padded for symmetry. If the document is for Ida's own use, settle how she'll use it before drafting: what she reads first leads, each practice is headed by its action or question, and each reference names its content (the statement, the quote, the person) instead of pointing at it. If the draft is weak at this level — wrong shape, wrong register, tells throughout — do not tune it. Go back to the source material and rewrite from it with the norms in front of you. Tuning a weak draft polishes the wrong thing.

   **Rewrite by claim checklist — the claim is the unit of fidelity, never the sentence.** In heavy mode this checklist is the seed's Substance list, already written (Step 0); in light mode, list the claims first — every fact, number, hedge, and attribution, quotes marked verbatim. Write the passage fresh from the list (sentence boundaries, count, and order are free), then verify against it: everything present, nothing invented, judgments at the same strength. The success test: a reader who knows the source finds every fact and caveat, and cannot map sentences one-to-one.

2. **Construction pass — build the prose; full method in `references/construction.md`.** Three diagnostics, applied to every sentence and passage:
   - **Sentence test:** read the first seven or eight words of each sentence (skip a short introductory phrase). They should reach a short, concrete subject naming the main character, then a verb naming its specific action. Flag abstract-noun subjects (nominalizations), seven-plus words before any verb, and empty verbs (is, has, occurred, was based). To rewrite: find the characters (hiding in possessives, of/by phrases, adjectives, or missing entirely), turn their actions from nouns back into verbs, make the characters the subjects, and join clauses with because, if, when, although.
   - **Flow test:** each sentence opens with information the reader already has and ends with what's new. Read the sentence openings in sequence — they should name a small, consistent set of topics. When old-before-new conflicts with active voice, old-before-new wins.
   - **Stress test:** the last few words of a sentence carry the emphasis. End on the newsworthy element, never a qualifier, an attribution, or a flourish. Fixes: trim the end, shift peripheral ideas left, shift new information right. A passage's opening sentence should end on the themes the passage develops.

   Apply the reference file's concision principles while rewriting (delete implied words, replace phrases with words, negatives to affirmatives). On short copy this step collapses to the sentence and stress tests — seconds, not minutes.

3. **Mechanical scan — run `scripts/scan.sh` on the draft file and look at every hit. Not optional, and not a final proofread: run it before you finalize so its hits shape the rewrite, and report its result in the revision note (step 8) so a skipped scan is visible.** For chat copy, write the draft to the scratchpad and scan it the same way. The script is the single source of truth for the scan strings; a hit is a judgment prompt, not an auto-delete. The categories it covers: contrast constructions and X-not-Y handles (`not just`, `it's not`, `, not `); em dashes (period or comma instead?); ` than ` — judge whether it lands at the end of a sentence or list item, the comparative-kicker position; aphoristic kickers (`the real`, `matters most`, `the one to`); marketing-CTA register (`worth` + gerund, `Have a look`, `Learn more`, `Explore`, `Discover`, `→`); intensifiers and weasel words; passive voice (judge each hit by the three passive questions in `references/construction.md` — passive is sometimes the right choice); nominalization chains; duplicate words; drama filler; and the vocabulary tells (`delve`, `crucial`, `leverage`, `utilize`, `foster`, `landscape`, the `sharpen` family, `straightforward`, `comprehensive`, `robust`) that slip past a constructions-only scan. A clean scan is necessary but not sufficient: it can't see a nameable category noun or a subtle appositive tail, so step 4's reading checks carry those, and a clean scan is never a finished pass.

4. **Named checks — answer each one; none is optional.**
   - **Headings:** read all headings alone, as a list. Each must state what its section contains. Rewrite any that tease, react, or fill, or that fail the five patterns under Headings above (count, question, source, metaphor verb, pronoun). Three tests from 2026-09-23, on taglines, decks, and subheads especially: it names a specific thing, not an abstraction ("One method, warranted" fails); it never tells the reader how to feel ("the part a lawyer will enjoy" fails); parallel subheads carry the noun, not a pronoun chain ("what it warrants / what it leaves unsaid" fails). The register to match is a grounded New Yorker deck, not a clickbait tease.
   - **List shape:** if three or more items in a list end the same way (same rhythm, same punchy landing), vary them or convert to prose.
   - **Name the members:** sweep every category noun and "thing you can/do to X" phrase; name short, known members. The scan flags the tell phrases, but a bare category noun it can't, in body prose and interface strings alike.
   - **Appositive tails:** read each sentence's ending; rewrite "[clause], [short appositive]" as a full clause or cut it. The scan catches the literal forms; read for the rest.
   - **Coined labels:** if the draft invented a two-or-three-word handle and built on it, replace every use with the plain description. Names that have to stay (a concept, a label on a page, a YAML key, a file name, a script flag) and that Claude or another model coined: list them for Ida to approve or rename before the deliverable ships. Usually the list is empty.
   - **Physically true verbs:** picture each verb happening to its subject; replace any action that can't happen to that thing, and any physical verb borrowed for an abstraction (lands, sits at, surfaces, carries).
   - **Explaining something new:** if the reader is new to the material, run the three checks under Explaining Something New: terms sorted by kind with double-duty words flagged, no term used before its definition (diagrams and labels included), and every rule given its cause.
   - **Idiom and jargon:** any idiom or term of art Ida doesn't already use gets replaced with the literal action; technical terms are defined inline on first use.
   - **Register and gestalt:** does any line read as a pitch, an ad, or prose impressed with itself — crowning its own claims, escalating without new evidence? Would a competent person say this sentence aloud to a colleague? When in doubt, compare against `references/exemplars.md`: the bar states a claim and supplies the evidence; the anti-bar states a claim and praises it.
   - **Prose about itself:** cut any sentence about the writing or the reader instead of the subject — meta-commentary labels ("Why it lands"), pre-handled objections, "why this matters" framing. See the classic-style principles in `references/craft-principles.md`.

5. **Grounding audit — claims and numbers, not just phrasing.** Go through every claim or figure the piece rests on and do one of: point to the primary source, cut it, or recast it as an open question. Verify numbers against the primary file, never a subagent's summary (a summary is a lead, not a source). Tag each claim by evidence type — sourced fact vs. inference, and internal/self-knowledge vs. external/market — and don't let an internal source settle a market question. Keep genuinely grounded claims firm; this is calibration, not blanket hedging.

6. **For each hit, do one of three things:** ground it (state the specific or sourced version), complete it (turn a fragment into a full sentence), or cut it.

7. **Scale to the stakes — depth, never coverage.** Length scales the structural work, the passage-level construction diagnostics (flow, topic strings), and the grounding audit — not the checks. A two-line copy block still gets the sentence and stress tests, the full mechanical scan, and the register check; short copy is where register tells concentrate and every word counts.

8. **Revision note.** End with a one-line Markdown blockquote beginning `> Revision pass:` (renders like `> Verified:`, so it reads as required output, not prose). Light mode leads with the scan result: `> Revision pass: scan 14→9, 5 kept; two teasing headers rewritten` (or `> Revision pass: scan clean`). Heavy mode uses fixed fields, a missing one flagging a skipped step: `> Revision pass: seed 11 particulars | scan 14→9 | members 2 named | tails 3 rewritten`. The scan count is required. One line, in chat, never the file; observability, not ceremony.

### Log entries and durable notes

When the prose is a log entry, notebook entry, or addition to running notes, run this compact variant: summarize the outcome rather than narrating the play-by-play; neutral verbs, no intensity beats ("that's the name," "couldn't crack," "the breakthrough"); match the density and register of the entries already in the file; run the mechanical scan. A log is a reference document read months later, not a recap of how the session felt.

## Gotchas

- **Synthesis fuses adjacent ideas into a wrong middle conclusion.** Two distinct claims in source don't authorize a third connecting claim. Preserve them as distinct. If a relationship between ideas isn't stated in the source, it doesn't go in the deliverable.
- **Synthesis degrades the source.** The source material is the ceiling, not the floor. Resist reframing, editorializing, or "improving" while organizing. Any sentence in the synthesis that can't be traced to a specific source must be cut.
- **A flagged instance is a sample, not an incident.** When Ida catches a wording or naming failure, sweep the whole deliverable for that class — a grep or one targeted read-through — before or immediately after fixing the instance she named. Each catch marks a class already in the document; fixing only the named instance ships the rest.
- **Diagnostic register and contrastive framing recur within a session even after correction.** Both are deep instincts, not one-off slips. After writing or revising, scan headings and topic sentences again — even sections already corrected — for prescription, warning, or "most X don't Y" framing.
- **Titles, citations, and URLs get generated instead of retrieved.** Default is retrieval — open the source, read the file, check the page. Never generate a title from memory or inference. Especially damaging for Ida's own published work.
- **Call preps drift into briefing memos.** Cue cards, not memos. Questions and decision points only — short bullets. No internal reasoning, no narrating Ida's instincts, no restating context she already carries. Halve any draft that reads like a briefing.