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

Problem (quote)	Diagnosis (why it fails)	Fix (rule)
Original problematic text	Specific issue identified	Corrected version + principle

Example

Problem	Diagnosis	Fix
"The thing that I want to say is..."	Filler phrase, delays main point	"I argue that..." (Get to the point)
"It is important to note that..."	Passive construction, weak	"Note that..." or delete entirely
"In today's modern society..."	Redundant (today = modern)	"Today..." (Eliminate redundancy)

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