---
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, which has its own drafting path. 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.

## 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.

## Writing Norms

### Sentences and Words

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

**Concrete over abstract.** Name the thing, not the category.

**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.

**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.

### 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.

## 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 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.** Extract the passage's claims into a checklist first: every fact, number, confidence, hedge, and attribution, with quotes marked verbatim. Write the passage fresh from the checklist — sentence boundaries, sentence count, claim order, and which claim leads are all free. Then verify the checklist against the new text: everything present, nothing invented, judgments at the same strength. The checklist is what makes rewriting safe, and it audits the prior draft too — the 2026-07-17 reckoning test caught two claims the earlier build had silently dropped and a hedge the line edit itself had weakened. "Preserve the substance" means preserve the checklist, never the wording. The success test for a rewrite: a reader who knows the source finds every fact and every 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.

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.
   - **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.
   - **Coined labels:** if the draft invented a two-or-three-word handle and built on it, replace every use with the plain description.
   - **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 load-bearing claim or figure 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 single terse line in chat, formatted as a one-line Markdown blockquote that always begins `> Revision pass:` — the blockquote renders italic with a left band, matching the `> Verified:` block, so it reads as a required mechanical output rather than prose. It leads with the scan result, then names what the pass changed: `> Revision pass: scan 14 → 9 fixed, 5 kept as meaningful; rewrote two teasing headers, cut three kickers` (or `> Revision pass: scan clean` when nothing fired and nothing needed changing). The scan count is required — a note without it means `scripts/scan.sh` (step 3) was skipped, which is not allowed. The fixed prefix plus the scan count is what makes the note countable and makes a skipped scan visible. Never longer than one line; this is observability, not ceremony. The note goes in chat, never in the file.

### 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.