Revision Framework

This skill provides systematic methodology for revising prose from structure to style.

Core Methodology: 3-Column Revision

The 3-column method is a systematic approach to identifying and fixing prose problems.

The Three Columns

Example

Revision Levels: Top-Down Approach

Revise in this order - structure before style:

Level 1: Structure (Macro)

Fix big-picture issues before line-level edits.

Check for:

• •✅ Clear thesis or main point
• •✅ Logical flow of sections
• •✅ Each paragraph has one main idea
• •✅ Transitions connect ideas
• •✅ Opening hooks and closing delivers
• •✅ No tangents or irrelevant sections

Questions to ask:

• •Does every paragraph serve the thesis?
• •Is the order of sections logical?
• •Can I cut any section without losing the argument?
• •Where does the reader get lost or confused?

Level 2: Style (Meso)

Fix paragraph and sentence-level issues.

Check for:

• •✅ Active voice (not passive)
• •✅ Strong verbs (not weak ones)
• •✅ Concrete nouns (not vague ones)
• •✅ Varied sentence length and structure
• •✅ Clear subjects (avoid "it" and "there")
• •✅ Parallel structure in lists
• •✅ Rhythm and flow

Questions to ask:

• •Can I make this sentence shorter?
• •Can I replace weak verbs (is, have, do) with stronger ones?
• •Are my subjects clear and concrete?
• •Do sentences vary in length and structure?

Level 3: Mechanics (Micro)

Final polish - grammar, word choice, punctuation.

Check for:

• •✅ Grammar and punctuation
• •✅ Precise word choice
• •✅ Consistent tense and voice
• •✅ No typos or misspellings
• •✅ Proper formatting (markdown, frontmatter)

Questions to ask:

• •Is every word the right word?
• •Can I use a more precise or vivid word?
• •Are there any errors?

Common Prose Problems & Fixes

1. Weak Verbs

Problem: Relying on "is", "have", "do", "get", "make"

Examples:

• •

  ❌ "The function is responsible for handling errors"

• •

  ✅ "The function handles errors"

• •

  ❌ "We made a decision to pivot"

• •

  ✅ "We decided to pivot"

Rule: Replace weak verbs with action verbs.

2. Passive Voice

Problem: Hiding the actor, making prose indirect

Examples:

• •

  ❌ "The bug was fixed by the team"

• •

  ✅ "The team fixed the bug"

• •

  ❌ "It is believed that AI will transform work"

• •

  ✅ "AI will transform work"

Rule: Use active voice unless you specifically want to hide the actor.

Exception: Passive is OK when:

• •Actor is unknown: "The server was attacked"
• •Actor doesn't matter: "The code was deployed"
• •You want to emphasize object: "The Constitution was ratified in 1788"

3. Vague Language

Problem: Abstract or general terms that don't create clear images

Examples:

• •

  ❌ "The situation was challenging"

• •

  ✅ "We missed three deadlines and lost our biggest client"

• •

  ❌ "Performance improved significantly"

• •

  ✅ "Response time dropped from 800ms to 200ms"

Rule: Replace vague with specific. Use numbers, names, details.

4. Redundancy

Problem: Saying the same thing twice or using unnecessary words

Examples:

• •

  ❌ "End result", "future plans", "past history"

• •

  ✅ "Result", "plans", "history"

• •

  ❌ "In my personal opinion, I think that..."

• •

  ✅ "I think..."

• •

  ❌ "The reason why is because..."

• •

  ✅ "Because..."

Rule: Cut every word that doesn't add meaning.

5. Filler Phrases

Problem: Throat-clearing that delays the main point

Common fillers to cut:

• •"It is important to note that..."
• •"I would like to say that..."
• •"The thing is that..."
• •"What I mean is..."
• •"In order to..."
• •"Due to the fact that..."
• •"It is worth mentioning that..."

Rule: Get to the point immediately.

6. Nominalization

Problem: Turning verbs into nouns, making prose stiff

Examples:

• •

  ❌ "We conducted an investigation" (nominalization: investigation)

• •

  ✅ "We investigated"

• •

  ❌ "The implementation of the feature" (nominalization: implementation)

• •

  ✅ "Implementing the feature" or "The feature"

Rule: Convert noun forms back to verbs when possible.

7. Hedging (Over-qualification)

Problem: Weakening claims with unnecessary hedges

Examples:

• •

  ❌ "It seems like this might possibly work"

• •

  ✅ "This might work" or "This works"

• •

  ❌ "I would argue that it could be said that..."

• •

  ✅ "I argue that..."

Rule: Commit to your claims. One qualifier is enough.

Exception: Hedging is appropriate when:

• •Claim is uncertain: "This data suggests..."
• •Acknowledging limitations: "In most cases..."
• •Building ethos: "I believe..." (shows humility)

8. Repetition

Problem: Repeating the same word, phrase, or idea

Types:

• •Word repetition: Using the same word too close together
• •Idea repetition: Saying the same thing in different words
• •Structure repetition: Every sentence starts the same way

Examples:

• •

  ❌ "The system processes the data and then the system validates it"

• •

  ✅ "The system processes the data and validates it"

• •

  ❌ "This is crucial. This is essential. This is vital."

• •

  ✅ "This is crucial."

Rule: Vary vocabulary and structure. Don't repeat unless intentional (rhetoric).

9. Unclear Pronouns

Problem: "It", "this", "that", "they" without clear referent

Examples:

• •❌ "We launched the feature and received feedback. This was encouraging."
  • •(This = launch? feedback? both?)
• •✅ "We launched the feature and received feedback. The positive feedback was encouraging."

Rule: Make pronoun references crystal clear, especially for "this" and "that".

10. Sentence Length Monotony

Problem: All sentences the same length, creating monotonous rhythm

Fix: Vary sentence length deliberately.

• •Short sentences: Emphasis, clarity, urgency
• •Medium sentences: Standard explanations
• •Long sentences: Complex ideas, building to climax

Example:

• •❌ "The project failed. We missed deadlines. The client was unhappy. We lost the contract."
• •✅ "The project failed. We missed three critical deadlines, the client grew increasingly frustrated, and ultimately we lost the contract."

Rule: Alternate between short, medium, and long sentences.

TK Placeholders

Use [TK: description] to mark gaps during drafting:

Common TK uses:

• •[TK: find citation] - Need to research source
• •[TK: add example] - Concept needs illustration
• •[TK: verify this claim] - Fact-check required
• •[TK: expand this section] - Needs more development
• •[TK: better transition] - Flow needs work

Finding TKs: make search TERM="[TK:"

Rule: Every TK must be resolved before publishing.

House Rulebook Compliance

When revising, enforce these principles:

1. Markdown as Source of Truth

• •No weird formatting hacks
• •Clean, readable markdown
• •Exports are derivatives

2. One File Per Idea

• •If piece covers multiple independent ideas, split it
• •Each file should have single clear thesis

3. Append, Don't Delete

• •Keep drafts and iterations (version control)
• •Archive completed work, don't delete

4. Utilitarian Filenames

• •Filename is for finding, not reading
• •Title lives inside file as # Title

5. Clean Linking

• •Use relative paths: [text](../reference/guide.md)
• •Or wiki-style: [[filename]]
• •Run make check-links before committing

Revision Checklist

Use this checklist when revising:

Structure ✅

• • Clear thesis or main point
• • Logical section order
• • Each paragraph = one idea
• • Strong opening and closing
• • No tangents or irrelevant content
• • Smooth transitions between sections

Style ✅

• • Active voice (unless passive is intentional)
• • Strong verbs (not is/have/make/get/do)
• • Concrete nouns (not vague generalities)
• • No filler phrases
• • No redundancy
• • Clear pronoun references
• • Varied sentence length
• • Appropriate hedging (not too much)

Mechanics ✅

• • Grammar and punctuation correct
• • Precise word choice
• • Consistent tense and voice
• • Proper markdown formatting
• • YAML frontmatter complete (if blog post)
• • No TK placeholders remaining
• • No typos or misspellings

House Rulebook ✅

• • Clean markdown (no formatting hacks)
• • One idea per file
• • Internal links are valid
• • Filename is utilitarian
• • Title inside file

Revision Workflow

1. Run Lint First

make lint
make lint-fix  # Auto-fix formatting issues

2. Structural Pass

Read through once, focusing only on:

• •Is the order right?
• •Does every paragraph serve the thesis?
• •Are there gaps in logic or flow?

Output: Reorder sections, cut tangents, add transitions

3. Style Pass

Read paragraph by paragraph, focusing on:

• •Active voice?
• •Strong verbs?
• •Clear subjects?
• •Varied sentence length?

Output: Rewrite weak sentences, combine short ones, split long ones

4. Mechanical Pass

Read line by line, focusing on:

• •Is every word the right word?
• •Are there errors?
• •Is formatting correct?

Output: Fix typos, improve word choice, polish

5. TK Resolution

Search for all TK placeholders:

make search TERM="[TK:"

Output: Research and fill every gap, or delete if not needed

6. Final Link Check

make check-links

Output: Fix any broken internal links

Working with Pipeline Stages

Adjust revision depth based on pipeline stage:

Capture/Cluster (Monday/Tuesday)

Revision needed: None - just capture ideas Focus: Get ideas down, don't edit

Outline (Wednesday)

Revision needed: Structure only Focus: Logical flow, does argument hold together?

Draft (Thursday)

Revision needed: Minimal - mark gaps with TK Focus: Get words on page, accept imperfection

Revise (Friday)

Revision needed: FULL - structure, style, mechanics Focus: Apply 3-column method, systematic improvement Workflow: Top-down (structure → style → mechanics)

Review (Saturday)

Revision needed: Based on feedback Focus: Address reviewer notes, final improvements

Publish (Sunday)

Revision needed: Final polish only Focus: Typos, last TK checks, formatting

3-Column Revision Template

Use this template to systematically improve prose:

## 3-Column Revision: [File Name]

| Problem (quote) | Diagnosis (why it fails) | Fix (rule) |
|-----------------|-------------------------|------------|
| "original text" | [issue] | "corrected text" ([principle]) |
| "original text" | [issue] | "corrected text" ([principle]) |
| "original text" | [issue] | "corrected text" ([principle]) |

## Patterns Observed

[Common issues that appear multiple times]

## Rules to Remember

1. [Rule learned from this revision]
2. [Rule learned from this revision]
3. [Rule learned from this revision]

Advanced Techniques

Reverse Outline

After drafting, create an outline from what you wrote:

1. •Write a one-sentence summary of each paragraph
2. •Check if the flow makes sense
3. •Reorder or delete paragraphs that don't fit

Purpose: Reveals structural issues hidden when reading normally.

Read Aloud

Read your draft out loud (or use text-to-speech).

Catches:

• •Awkward phrasing
• •Rhythm problems
• •Repetition
• •Missing words
• •Sentences too long to read in one breath

Reader's Perspective

Ask these questions:

• •Where would I get bored?
• •Where would I get confused?
• •What would I skip?
• •What would I question?

Purpose: Anticipate reader reactions and fix preemptively.

Related Skills

• •argument-analysis: For checking logical structure
• •vault-context: For pipeline stages and workflows
• •blog-workflow: For publishing-specific revision

Instructions for Claude

When using this skill to revise:

1. •Always revise top-down - structure before style before mechanics
2. •Use 3-column method - explicitly state problem, diagnosis, fix
3. •Respect pipeline stage - don't over-edit drafts, go deep on revisions
4. •Mark gaps with TK - don't fake content, flag what needs research
5. •Apply house rulebook - enforce markdown, linking, file principles
6. •Suggest make commands - lint before revision, check-links after
7. •Work in advisory mode - suggest changes, user approves

For more details, see:

• •checklist.md - Complete revision checklist