writing-revision
$
npx mdskill add lyndonkl/claude/writing-revisionPolishes drafts by cutting clutter and improving rhythm.
- Helps users reduce word count and tighten prose.
- Depends on Zinsser, King, Pinker, and Clark frameworks.
- Decides edits by analyzing text for cognitive load.
- Delivers revised text with improved flow and readability.
SKILL.md
.github/skills/writing-revisionView on GitHub ↗
--- name: writing-revision description: Applies a systematic three-pass revision system (Zinsser, King, Pinker, Clark) to existing drafts — Pass 1 cuts clutter, Pass 2 reduces cognitive load, Pass 3 improves rhythm. Use when revising, editing, or polishing drafts, cutting word count, tightening prose, improving readability, or fixing flow, or when user mentions revision, editing, cut clutter, too wordy, improve readability, fix the flow, reduce word count. --- # Writing Revision (Three-Pass System) ## Table of Contents - [Core Principles](#core-principles) - [Workflow](#workflow) - [Pass Overview](#pass-overview) - [Guardrails](#guardrails) - [Quick Reference](#quick-reference) **Related skills:** Use `writing-structure-planner` for planning structure, `writing-stickiness` for memorable messaging, `writing-pre-publish-checklist` for final publishing checks. ## Core Principles 1. **One focus per pass**: Each pass targets one dimension rather than fixing everything at once 2. **Cut 10-25%**: King's formula - second draft equals first draft minus 10-25% 3. **Every word earns its place**: If a word doesn't contribute, remove it 4. **First reading is correct reading**: Readers shouldn't need to re-read sentences (Pinker) 5. **Rhythm creates engagement**: Varied sentence lengths and strong endings keep readers moving ## Workflow Copy this checklist and track your progress: ``` Three-Pass Revision: - [ ] Pass 1: Cut clutter (analyze -> improve) - [ ] Pass 2: Reduce cognitive load (analyze -> improve) - [ ] Pass 3: Improve rhythm (analyze -> improve) ``` **Before starting:** Review [resources/revision-guide.md](resources/revision-guide.md) for the complete three-pass system with examples and the full transformation demonstration. For each pass, analyze the entire draft first and output findings to an analysis file in the current directory, then read that file to make improvements. This ensures complete coverage. ### Pass 1: Cut Clutter (Zinsser/King) **Goal:** Cut 10-25% of word count. Make every word earn its place. Step 1.1 - Analysis: Read entire draft. Create analysis file `writer-pass1-clutter-analysis.md` identifying all instances of: adverbs (-ly words), qualifiers (very, really, quite, somewhat), passive voice, weak verbs (is, are, was, were, has/have/had), throat-clearing phrases, and cliches. Calculate word count and set target for 10-25% reduction. Step 1.2 - Improvement: Read analysis file. Work through entire draft making improvements: remove 70% of adverbs, delete qualifiers, convert passive to active voice, replace weak verbs with action verbs, eliminate throat-clearing, remove cliches. Verify word count reduction meets 10-25% target. Ensure every remaining word earns its place. See [resources/revision-guide.md - Pass 1](resources/revision-guide.md#pass-1-cut-clutter-zinsserking) for detailed examples. ### Pass 2: Reduce Cognitive Load (Pinker) **Goal:** Make reading effortless. First reading should be correct reading. Step 2.1 - Analysis: Read entire draft. Create analysis file `writer-pass2-cognitive-load-analysis.md` identifying all issues: garden-path sentences (temporarily mislead readers), buried topics, subject-verb-object separated by more than 7 words, ambiguous pronouns, broken topic chains, sentences requiring re-reading. Step 2.2 - Improvement: Read analysis file. Work through entire draft: fix garden-path sentences, signal topic at start of each sentence, keep subject-verb-object close, clarify pronouns, repair topic chains, break overly complex sentences. Read aloud to verify no stumbles. See [resources/revision-guide.md - Pass 2](resources/revision-guide.md#pass-2-reduce-cognitive-load-pinker) for detailed examples. ### Pass 3: Improve Rhythm (Clark) **Goal:** Create engaging flow through sentence variety and strong endings. Step 3.1 - Analysis: Read entire draft. Create analysis file `writer-pass3-rhythm-analysis.md` analyzing: sentence lengths for each paragraph (list actual lengths), monotonous patterns (5+ similar-length sentences in a row), last word of each sentence (mark weak endings), gold-coin placement (identify gaps), opportunities for ladder of abstraction (concrete -> general -> concrete), sections lacking variety. Step 3.2 - Improvement: Read analysis file. Work through entire draft: add short sentences for emphasis after longer ones, replace weak sentence endings with strong words, distribute gold-coin moments throughout (especially middle), apply ladder of abstraction, vary sentence lengths deliberately. Read aloud to verify flow. Confirm good mix of short, medium, and long sentences. See [resources/revision-guide.md - Pass 3](resources/revision-guide.md#pass-3-improve-rhythm-clark) for detailed examples. Validate using [resources/evaluators/rubric_revision.json](resources/evaluators/rubric_revision.json). **Minimum standard**: Average score >= 3.5. ## Pass Overview | Pass | Focus | Method | Target | |------|-------|--------|--------| | Pass 1 | Clutter | Zinsser/King | Cut 10-25% word count | | Pass 2 | Cognitive Load | Pinker | No re-reading needed | | Pass 3 | Rhythm | Clark | Varied lengths, strong endings | ## Guardrails **Requirements:** 1. **Preserve meaning**: Keep the author's intended meaning intact while cutting or restructuring 2. **Analyze before improving**: Always create the analysis file first, then make improvements based on findings 3. **Complete coverage**: Analyze the entire draft in each pass, not just the first few paragraphs 4. **Measure reduction**: Track actual word count reduction in Pass 1 (target 10-25%) 5. **Read aloud**: After Passes 2 and 3, verify by reading aloud for stumbles and rhythm **Common pitfalls:** - Trying to fix everything in one pass (stick to one focus per pass) - Only revising the opening paragraphs and losing steam - Cutting so aggressively that voice is lost - Not tracking actual word count reduction - Skipping the analysis phase and jumping straight to editing ## Quick Reference **Key resources:** - **[resources/revision-guide.md](resources/revision-guide.md)**: Complete three-pass system with before/after examples - **[resources/evaluators/rubric_revision.json](resources/evaluators/rubric_revision.json)**: Quality scoring criteria **Inputs required:** - Draft text to revise (any stage) - User's intent or core message (if known) - Any constraints (word count target, tone preferences) **Outputs produced:** - Analysis files for each pass (clutter, cognitive load, rhythm) - Revised draft with tracked word count reduction - Summary of changes made in each pass
More from lyndonkl/claude
- abstraction-concrete-examplesBuilds structured abstraction ladders that translate high-level principles into concrete, actionable examples across 3-5 levels. Bridges communication gaps, reveals hidden assumptions, and tests whether abstract ideas work in practice. Use when explaining concepts at different expertise levels, moving between abstract principles and concrete implementation, identifying edge cases by testing ideas against scenarios, designing layered documentation, decomposing complex problems into actionable steps, or bridging strategy-execution gaps.
- academic-letter-architectGuides the creation of evidence-based academic recommendation letters, reference letters, and award nominations that combine concrete examples, meaningful comparisons, and genuine enthusiasm. Use when writing recommendation letters for students, postdocs, or colleagues, or when user mentions recommendation letter, reference, nomination, letter of support, endorsement, or needs help with strong advocacy and comparative statements.
- adr-architectureDocuments significant architectural and technical decisions with full context, alternatives considered, trade-offs analyzed, and consequences understood. Creates a decision trail that helps teams understand why decisions were made. Use when choosing between technology options, making infrastructure decisions, establishing standards, migrating systems, or when user mentions ADR, architecture decision, technical decision record, or decision documentation.
- adverse-selection-priorProduces a Bayesian prior probability that an offered transaction is +EV for the recipient, given that the counterparty chose to propose it. Applies Akerlof market-for-lemons logic -- if they offered it, they believe it is +EV for them, so the prior that it is +EV for us is materially below 50%. Reusable across trade evaluation, waiver drops (another team dropping a player is also adverse selection), job-offer analysis, M&A, and any "someone offered me this" situation. Use when you receive an unsolicited trade/offer/proposal, analyzing incoming trade prior, evaluating why a counterparty proposed a deal, or when user mentions adverse selection, market for lemons, why did they offer this, incoming trade prior, they proposed it, Bayesian adjustment on received offer.
- alignment-values-north-starCreates actionable alignment frameworks that give teams a shared North Star (direction), values (guardrails), and decision tenets (behavioral standards). Enables autonomous decision-making while maintaining organizational coherence. Use when starting new teams, scaling organizations, defining culture, establishing product vision, resolving misalignment, creating strategic clarity, or when user mentions North Star, team values, mission, principles, guardrails, decision framework, or cultural alignment.
- analogy-weight-checkFor every analogy in a substacker draft, verifies it carries mechanical weight — the analogy does real work explaining the mechanism, not merely decorates it. Cross-references analogy-catalog.md for novelty (is this analogy reused from a prior post?) and domain fit (biology > organizational > sports preferred; physics/military disfavored). Use whenever an analogy appears in the draft. Trigger keywords: analogy weight, decorative, mechanical weight, reused analogy, catalog check, metaphor check.
- answer-uncomfortable-questionTakes one strategic question about substacker ("should we launch paid?", "is this section dead?", "are we writing for the wrong audience?") and produces the mandatory evidence + reasoning + downside triad plus a recommendation. Used 3 times per Growth Strategist review. Trigger keywords: uncomfortable question, strategic question, evidence reasoning downside, triad.
- attribute-performanceFor each substacker post that materially over- or under-performs the rolling baseline (|z| ≥ 1.0), produces a plain-English attribution paragraph with calibrated confidence (high / medium / low / unexplained). Considers subject-line effect, topic zeitgeist, external share, day-of-week, length effect, and audience-notes signals. Labels unexplained outliers explicitly rather than fabricating a story. Use after compute-baseline when outlier posts exist. Trigger keywords: attribution, why did this post work, outlier explanation, performance analysis.
- auction-first-price-shadingComputes the optimal shaded bid for a first-price sealed-bid auction given a true private value, an estimate of the number of competing bidders N, and a value-distribution assumption. Implements the `(N-1)/N` equilibrium shading rule for uniform private values, adjusts for log-normal or empirical value distributions, layers a risk-aversion adjustment, and caps output against the bidder's remaining budget. Domain-neutral auction theory reusable across fantasy sports (baseball FAAB, NBA/NHL waiver auctions), prediction-market limit sizing, sealed procurement bids, and any blind-bid context. Use when user mentions "first-price auction bid", "sealed bid shading", "(N-1)/N", "FAAB bid amount", "auction shading", "optimal bid first-price", "bid for sealed-bid", "blind bid sizing", or when downstream logic needs a principled shade factor rather than an ad-hoc heuristic.
- auction-winners-curse-haircutApplies a Bayesian haircut to a bid valuation for common-value auctions where winning is itself evidence the bidder over-estimated. Takes a raw valuation, a value-type classification (common_value / private_value / mixed), the number of informed bidders N, and a signal-dispersion estimate, and returns an adjusted valuation. Domain-neutral and reusable across fantasy FAAB, prediction markets, M&A bids, ad-auction budgets, and any generic bidding context. Use when user mentions "winner's curse", "common value auction", "valuation haircut", "adverse valuation", "Bayesian bid adjustment", or "over-paying in auction".