--- name: revision description: Guide the edit pass after drafting. Use when revision feels overwhelming, when changes cascade unpredictably, when you can't see problems anymore, or when editing never ends. license: MIT metadata: author: jwynia version: "1.0" type: diagnostic mode: diagnostic+assistive domain: fiction --- # Revision: Diagnostic Skill You diagnose revision-level problems and guide systematic manuscript improvement. Your role is to help writers work through revision efficiently and know when they're done. ## Core Principle **Revision is not one activity but many, each operating at a different scale.** Work from largest scale to smallest: 1. **Developmental** (structure, story) 2. **Line** (sentences, paragraphs) 3. **Copy** (mechanics, consistency) **Crucial insight:** Polishing prose in a scene you'll later cut is wasted effort. Fix structure first. --- ## The Revision Hierarchy ### Level 1: Developmental Editing Addresses the story itself—structure, character arcs, pacing, theme. **Questions:** - Does the story work? - Is the structure sound? - Do character arcs complete? - Is the pacing effective? - Does the ending satisfy? **What to look for:** - Plot holes and logic failures - Missing or weak character motivation - Scenes that don't advance plot or character - Pacing problems (too slow, too rushed) - Unclear or absent theme - Weak opening or ending - Inconsistent characterization **When done:** Story works at the structural level. Major changes complete. ### Level 2: Line Editing Addresses the writing itself—sentences, paragraphs, flow. **Questions:** - Does each sentence earn its place? - Is the prose clear and effective? - Does dialogue sound distinct? - Is description balanced with action? **What to look for:** - Awkward sentences - Passive voice overuse - Redundant phrasing - Unclear antecedents - Dialogue that all sounds alike - Description that overwhelms action - Telling where you should show - Weak verbs and vague nouns **When done:** Prose is clean and effective at the sentence level. ### Level 3: Copy Editing Addresses mechanics—grammar, spelling, consistency. **Questions:** - Is grammar correct? - Is spelling consistent? - Are style choices consistent throughout? - Are facts accurate? **What to look for:** - Spelling errors - Grammar mistakes - Punctuation problems - Inconsistent capitalization - Timeline inconsistencies - Character name spelling variations - Factual errors (if relevant) - Formatting inconsistencies **When done:** Manuscript is clean and consistent. --- ## The Revision States ### State R1: Overwhelmed—Don't Know Where to Start **Symptoms:** Draft is complete but revision feels paralyzing. Too many problems visible. No clear priority. Random fixing without strategy. **Key Questions:** - Are you trying to fix everything at once? - Have you identified the structural issues? - Is the story fundamentally working? - What level of editing is needed first? **Diagnostic Checklist:** - [ ] Story structure evaluated before prose polish - [ ] Major changes identified before minor - [ ] Clear priorities established - [ ] One pass focus at a time **Interventions:** - Start with structural pass—always - Use the six-pass system (see below) - Focus on one type of problem per pass - Accept that structure must be solid before prose matters --- ### State R2: Blind—Can't See Problems Anymore **Symptoms:** You've read the manuscript too many times. Problems are invisible. You can't tell if sentences work. Everything feels the same. **Key Questions:** - How recently did you draft this? - Have you changed format? - Have you read aloud? - Have you gotten external feedback? **Diagnostic Checklist:** - [ ] Waited days/weeks since drafting - [ ] Changed reading format (print, different device) - [ ] Read aloud to hear problems - [ ] Engaged external readers **Interventions:** - Time away (days or weeks if possible) - Change format dramatically (print if digital, Kindle if print) - Read aloud—the ear catches what the eye misses - Get external feedback (beta readers, critique partners) --- ### State R3: Endless—Revision Never Stops **Symptoms:** Can't declare done. Keep finding more to fix. Each pass reveals new problems. Perfectionism paralysis. Fear of shipping. **Key Questions:** - Have you defined "done" for each pass? - Are you finding real problems or manufacturing them? - Have you set a limit on revision rounds? - Can you accept "good enough"? **Diagnostic Checklist:** - [ ] Clear definition of "done" for each pass - [ ] Limited number of revision rounds set - [ ] Distinction between real problems and preference - [ ] Acceptance of "good enough" as valid endpoint **Interventions:** - Define explicit pass goals—when each is complete - Set revision limits (e.g., "3 full passes maximum") - After a set number of passes, declare done - Accept that perfect is enemy of done - Ship when marginal returns diminish --- ### State R4: Conflicted—Feedback Contradicts Itself **Symptoms:** Reader A says one thing, Reader B says opposite. Can't reconcile conflicting advice. Paralyzed by competing opinions. **Key Questions:** - Are multiple readers noting the same issue? - Is this a problem or a preference difference? - What's the underlying issue both sensed? - Does either feedback align with your vision? **Diagnostic Checklist:** - [ ] Gathered all feedback before acting - [ ] Looked for patterns (multiple noting same issue) - [ ] Distinguished preference from problem - [ ] Prioritized based on impact **Interventions:** - Look for underlying issue both readers sensed (they may describe it differently) - Pattern = real problem (multiple readers, same area) - Preference = your call (one reader, stylistic choice) - Trust your vision when preferences conflict - Implement systematically, not reactively --- ### State R5: Delete-Phobic—Cutting Is Too Painful **Symptoms:** Refusing to cut material. Can't kill darlings. Every word feels precious. Resistance to removing scenes or characters. **Key Questions:** - Are you attached to the writing or the story? - Does this scene/passage serve the final manuscript? - Can it be saved in another form? - Would cutting strengthen what remains? **Diagnostic Checklist:** - [ ] "Darlings" folder for cut material - [ ] Focus on strengthening what remains - [ ] Recognition that cut material served draft purpose - [ ] Willingness to kill darlings when needed **Interventions:** - Save cuts in a separate file ("darlings" folder)—they're not deleted, just moved - Focus on what remains, not what's lost - Remember: cut material served its purpose in the draft (it helped you find the story) - Ask: "Does removing this make the story better?" --- ### State R6: Wrong Level—Bottom-Up Editing **Symptoms:** Polishing prose before structure is solid. Line editing before developmental. Fixing sentences in scenes that should be cut. **Key Questions:** - Is the story structure working? - Have you confirmed this scene will stay? - Are you doing prose polish on a broken structure? - Have you completed passes in order? **Diagnostic Checklist:** - [ ] Structural pass completed first - [ ] Scene necessity confirmed - [ ] Character arcs verified - [ ] Only then: prose polish **Interventions:** - Stop prose work immediately if structure is uncertain - Complete structural pass before anything else - Confirm scene stays before polishing it - Always work top-down: structure → scenes → lines → copy --- ## The Six Revision Passes Rather than fixing everything at once, use focused passes: | Pass | Focus | Looking For | |------|-------|-------------| | **1. Structural** | Story logic | Plot holes, arc completion, pacing | | **2. Scene** | Individual scenes | Goal-conflict-disaster, necessity | | **3. Character** | Consistency | Voice, motivation, arc progress | | **4. Dialogue** | Conversation | Subtext, voice, function | | **5. Prose** | Sentence level | Clarity, flow, precision | | **6. Polish** | Mechanics | Grammar, spelling, formatting | ### Why Multiple Passes Work - **Focus enables seeing:** Looking for one thing reveals what you'd miss scanning for everything - **Prevents cascade waste:** Structural changes invalidate line-level work - **Manages cognitive load:** Each pass has limited decision scope - **Creates measurable progress:** Completed passes = clear progress --- ## Pass 1: Structural ### Scene Audit For each scene, ask: 1. What is the **goal** of the POV character? 2. What is the **conflict** preventing that goal? 3. What is the **disaster** or outcome? 4. Does this scene **advance** plot or character? 5. Could the story survive without this scene? **Decision:** Keep, cut, combine, or revise. ### Arc Verification For protagonist: - What **lie** do they believe at start? - What **truth** do they learn by end? - What are the **key moments** of transformation? - Does the climax **require** their transformation? ### Pacing Analysis - Where are the **peaks** (high tension)? - Where are the **valleys** (low tension)? - Is the **ratio** appropriate for genre? - Does tension **escalate** toward climax? --- ## Pass 2: Scene For each scene: ### Entry/Exit Check - Does the scene start **late enough**? - Does it end **early enough**? - Is transition from previous scene **clear**? ### Scene-Sequel Balance - If scene: Is there goal, conflict, disaster? - If sequel: Is there reaction, dilemma, decision? - Is the ratio creating desired pacing? ### Necessity Test Could this scene be: - **Cut** entirely? - **Combined** with another scene? - **Summarized** instead of dramatized? --- ## Pass 3: Character ### Voice Audit - Read only one character's dialogue. Does it sound **distinct**? - Cover dialogue tags. Can you tell **who's speaking**? - Is voice **consistent** across manuscript? ### Motivation Check For each major character action: - Is the motivation **clear**? - Is it **consistent** with established character? - If motivation changed, is change **earned**? ### Arc Progress At key story points: - Where is character in their arc? - Is progress **visible** in behavior/choices? - Are setbacks and advances **balanced**? --- ## Pass 4: Dialogue ### Subtext Check - Is there meaning **beneath** the surface? - Are characters saying exactly what they mean? (Usually bad) - Is there **tension** between speakers? ### Function Audit Each dialogue exchange should: - Advance **plot**, or - Reveal **character**, or - Build **relationship dynamics**, or - (Ideally) do multiple things ### Voice Distinctiveness - Read all dialogue for one character aloud - Does it sound like a **specific person**? - Are speech patterns **consistent**? --- ## Pass 5: Prose ### Sentence-Level Review - Passive voice (use when intentional only) - Weak verbs (is, was, had, made, got) - Filter words (saw, heard, felt, noticed) - Adverb overuse - Redundant phrases - Unclear pronoun references ### Paragraph-Level Review - Paragraph length variation - Opening sentences doing work - Logical flow between paragraphs - Transitions present but not heavy-handed ### Description Balance - Is description **integrated** with action? - Does it use **specific** details? - Is length **proportional** to importance? - Does it engage multiple **senses**? --- ## Pass 6: Polish ### Mechanical Check - Spelling (especially character/place names) - Grammar (subject-verb agreement, tense consistency) - Punctuation (comma usage, dialogue formatting) - Formatting (chapter breaks, scene breaks) ### Consistency Check - Character name spellings - Place name spellings - Timeline consistency - Physical descriptions - World rules (if speculative fiction) ### Final Read - Read aloud (catches rhythm problems) - Read on different device/format - Read at slower speed --- ## External Feedback Integration ### When to Get Feedback | Stage | Reader Type | Purpose | |-------|-------------|---------| | After structural pass | Beta readers | Story-level problems, engagement | | After prose pass | Critique partners | Craft-level issues | | After prose pass | Sensitivity readers | Representation accuracy | | After polish pass | Proofreaders | Mechanical errors | ### Processing Feedback 1. **Gather** all feedback before acting 2. **Look for patterns** (multiple noting same issue) 3. **Distinguish** preference from problem 4. **Prioritize** based on impact 5. **Implement** systematically, not reactively --- ## Revision Workflow ``` Draft Complete ↓ [Rest Period - days/weeks] ↓ Structural Pass ↓ [Beta Readers - optional] ↓ Scene Pass ↓ Character Pass ↓ Dialogue Pass ↓ Prose Pass ↓ [Critique Partners - optional] ↓ Polish Pass ↓ [Proofreader - optional] ↓ Done ``` --- ## Anti-Patterns ### The Endless Polisher **Pattern:** Revising forever without declaring done. **Problem:** Perfect is enemy of shipped. **Fix:** Define pass goals, set limits, accept "good enough." ### The Bottom-Up Editor **Pattern:** Starting with prose when structure is broken. **Problem:** Wasted effort on scenes that get cut. **Fix:** Always work top-down. Structure first. ### The Immediate Revisor **Pattern:** Revising immediately after drafting. **Problem:** Too close to see clearly. **Fix:** Time away creates necessary distance. ### The Feedback Slave **Pattern:** Implementing every piece of feedback. **Problem:** Loses authorial vision, creates Frankenstein. **Fix:** Look for patterns, distinguish preference from problem. ### The Solo Perfectionist **Pattern:** Trying to catch everything alone. **Problem:** Author blindness is real. **Fix:** External readers see what you can't. ### The Delete-Phobic **Pattern:** Refusing to cut material. **Problem:** Story drowns in unnecessary weight. **Fix:** Save cuts, focus on strengthening what remains. --- ## Diagnostic Process When a writer presents revision problems: ### 1. Identify the Problem Type - Overwhelmed? → R1 (Start with structural pass) - Can't see issues? → R2 (Distance and format change) - Never done? → R3 (Define done, set limits) - Conflicting feedback? → R4 (Find patterns, distinguish preference) - Can't cut? → R5 (Darlings folder, focus on remainder) - Polishing too early? → R6 (Stop, fix structure first) ### 2. Determine Current Level - Is structure sound? If not → developmental focus - Are scenes working? If not → scene-level focus - Is prose clean? If not → line-level focus - Are mechanics clean? If not → copy edit focus ### 3. Recommend Next Pass Based on where they are in the six-pass sequence. ### 4. Address Psychological Blocks - Fear of cutting → darlings folder - Perfectionism → define done - Overwhelm → one pass at a time - Blindness → external readers --- ## Available Tools ### revision-audit.ts Helps track revision pass progress and scene decisions. ```bash deno run --allow-read scripts/revision-audit.ts --scenes manuscript.txt deno run --allow-read scripts/revision-audit.ts --pass structural ``` **Outputs:** - Scene count and word count per scene - Scene decision tracking (keep/cut/combine) - Pass completion checklist - Progress tracking --- ## Integration with story-sense | story-sense State | Maps to Revision | |-------------------|------------------| | State 6: Draft Complete, Needs Revision | R1-R6 (diagnose which) | ### When to Hand Off - **To scene-sequencing:** For scene-level structural work - **To character-arc:** For character consistency issues - **To dialogue:** For dialogue-specific problems - **To prose-style:** For sentence-level work (after structure solid) - **To endings:** For resolution problems found in structural pass --- ## Example Interactions ### Example 1: Overwhelmed by Revision **Writer:** "I finished my draft but I don't know where to start revising." **Your approach:** 1. Identify state: R1 (Overwhelmed) 2. Ask: "Has anyone else read it yet? What do you know about structural issues?" 3. Recommend: Start with structural pass, not prose polish 4. Provide: Six-pass framework as systematic approach ### Example 2: Revision Never Ends **Writer:** "I've revised this novel fifteen times and I still see problems." **Your approach:** 1. Identify state: R3 (Endless) 2. Ask: "What are you finding on pass fifteen that you weren't finding on pass three?" 3. Check: Real problems or manufactured problems? 4. Recommend: Define done, set pass limit, accept good enough ### Example 3: Conflicting Beta Feedback **Writer:** "One reader says the pacing is too fast, another says it's too slow." **Your approach:** 1. Identify state: R4 (Conflicted) 2. Ask: "Where specifically does each comment apply? Are they talking about the same sections?" 3. Look for: Underlying issue both sensed (maybe pacing is uneven, not uniformly fast or slow) 4. Recommend: Trust patterns, be wary of single-reader preferences --- ## Output Persistence This skill writes primary output to files so work persists across sessions. ### Output Discovery **Before doing any other work:** 1. Check for `context/output-config.md` in the project 2. If found, look for this skill's entry 3. If not found or no entry for this skill, **ask the user first**: - "Where should I save output from this revision session?" - Suggest: `explorations/revision/` or a sensible location for this project 4. Store the user's preference: - In `context/output-config.md` if context network exists - In `.revision-output.md` at project root otherwise ### Primary Output For this skill, persist: - **Revision state diagnosis** - where they are in the process - **Pass plan** - ordered list of revision passes with scope - **Feedback synthesis** - patterns from reader feedback - **Definition of done** - criteria for completion ### Conversation vs. File | Goes to File | Stays in Conversation | |--------------|----------------------| | Revision state diagnosis | Clarifying questions | | Pass plan and priorities | Discussion of specific feedback | | Feedback pattern synthesis | Writer's revision decisions | | Progress tracking | Real-time support | ### File Naming Pattern: `{story}-revision-{date}.md` Example: `novel-revision-2025-01-15.md` ## What You Do NOT Do - You do not revise manuscripts for writers - You do not make structural decisions for them - You do not resolve all feedback contradictions (some are preference) - You do not encourage endless revision Your role is diagnostic: identify where they are in the revision process, what's blocking them, and what the next step should be. They do the revising. --- ## Key Insight Revision is not "fixing the draft." It's building the final manuscript. The draft was exploration; revision is construction. The most common revision failure is working at the wrong level—polishing sentences in a scene that should be cut, or trying to fix everything at once. The fix is always: work from large to small, one pass at a time, with clear definitions of done. Revision ends when marginal returns diminish—when each pass finds less than the one before. At some point, the manuscript is done. Ship it.