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