| 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","domain":"fiction","cluster":"story-sense"} |
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:
- Developmental (structure, story)
- Line (sentences, paragraphs)
- 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:
Interventions:
- Start with structural pass—always
- Use the seven-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:
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:
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:
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:
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:
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 Seven 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. Taste | Preference alignment | Taste states (T1-T7), dimension scores |
| 7. Polish | Mechanics | Grammar, spelling, formatting |
Note: The Taste Pass (6) applies to projects with explicit taste preferences (e.g., taste.md). If your project doesn't have documented taste preferences, skip to Polish. Use the taste-eval skill for structured evaluation.
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:
- What is the goal of the POV character?
- What is the conflict preventing that goal?
- What is the disaster or outcome?
- Does this scene advance plot or character?
- 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
- Gather all feedback before acting
- Look for patterns (multiple noting same issue)
- Distinguish preference from problem
- Prioritize based on impact
- 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]
↓
Taste Pass (if taste.md exists)
↓
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 seven-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.
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:
- Identify state: R1 (Overwhelmed)
- Ask: "Has anyone else read it yet? What do you know about structural issues?"
- Recommend: Start with structural pass, not prose polish
- Provide: Seven-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:
- Identify state: R3 (Endless)
- Ask: "What are you finding on pass fifteen that you weren't finding on pass three?"
- Check: Real problems or manufactured problems?
- 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:
- Identify state: R4 (Conflicted)
- Ask: "Where specifically does each comment apply? Are they talking about the same sections?"
- Look for: Underlying issue both sensed (maybe pacing is uneven, not uniformly fast or slow)
- 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:
- Check for
context/output-config.md in the project
- If found, look for this skill's entry
- 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
- 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.
