revision

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:

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 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:

• 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 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:

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]
    ↓
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:

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: 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:

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.