# Revision Framework

> Apply 3-column revision method (problem/diagnosis/fix), detect weak phrasing, check clarity, enforce house-rulebook style. Use when revising drafts, improving prose quality, or when user asks to edit or refine writing.

- Skill: `majiayu000/revision-framework` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/revision-framework`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/revision-framework/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/revision-framework

---


# 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
```bash
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:
```bash
make search TERM="[TK:"
```

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

### 6. Final Link Check
```bash
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:

```markdown
## 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](checklist.md) - Complete revision checklist