Content Editing Skill

When to Use This Skill

• Reviewing completed drafts for quality
• Checking grammar, style, and mechanics
• Verifying factual accuracy and citations
• Ensuring terminology and voice consistency
• Preparing content for final formatting
• Conducting multi-pass editorial reviews

Editorial Workflow (Six-Pass System)

Pass 1: Structural Review (Macro Level)

• Document follows outline structure
• All sections have clear, distinct purposes
• Logical flow between sections
• Appropriate section lengths (no extreme outliers)
• Heading hierarchy consistent (H2 → H3 → H4, no skips)
• Chapter/section breakdown matches plan
• TOC-worthy headings properly formatted

• Does each section serve a clear purpose?
• Are topics in the most logical order?
• Are any sections too long and need splitting?
• Are any sections too short and should be combined?

Pass 2: Content Quality (Micro Level)

• Subject-verb agreement correct
• Verb tense consistent within sections
• Pronoun antecedents clear
• No sentence fragments (unless intentional)
• No run-on sentences
• No comma splices
• Proper punctuation throughout

• Every sentence has clear meaning
• No unnecessary words or phrases
• Complex ideas broken into manageable chunks
• Technical jargon defined or eliminated
• Ambiguous pronouns resolved

• Active voice predominates (target: >80%)
• Consistent perspective (you/we/one)
• Consistent tone (formal/balanced/conversational)
• Parallel structure in lists
• Varied sentence structure for rhythm

• Flesch Reading Ease appropriate for audience (see table below)
• Average sentence length matches complexity level
• Paragraph lengths appropriate (4-6 sentences typical)

📝 Note: Lower Flesch scores are acceptable for advanced topics. The goal is clarity for the intended audience, not a universal threshold.

Pass 3: Citation Verification (Accuracy Check)

• Every factual claim has citation
• Every statistic cited
• Every direct quote cited
• Every date/historical fact cited
• Every technical specification cited

• Consistent format throughout (APA/MLA/Chicago)
• In-text citations match reference list
• All citation elements present (author, year, title, source, URL, access date)
• Page numbers for quotes and specific claims

• Sources are authoritative (academic, reputable news, official docs)
• Sources are current (< 5 years unless historical)
• Multiple sources for major claims
• Primary sources used where possible

• Every cited source exists in research notes
• Source details match research documentation
• No "dead" citations (source cannot be located)

Pass 4: Consistency Audit (Uniformity Check)

# Check AI terminology consistency
grep -E "(AI|artificial intelligence|Artificial Intelligence|A.I.)" content/

# Check website spelling
grep -E "(web site|website|web-site)" content/

# Check hyphenation patterns
grep -E "(e-mail|email|Email)" content/

• Number style consistent (spell out 1-10 or always numerals)
• Date format consistent (Month Day, Year)
• Time format consistent (12-hour with am/pm or 24-hour)
• Oxford comma usage consistent
• Capitalization consistent (job titles, headings)
• Hyphenation consistent (compound modifiers, prefixes)

• Same perspective throughout (you/we/one)
• Same tone level maintained
• Same formality level

Pass 5: Visual Formatting Audit

📝 Note: Visual formatting rules are contextual, not rigid. Technical content benefits from more frequent visual breaks; conceptual/philosophical content may flow better with fewer interruptions. The goal is cognitive clarity, not arbitrary quotas.

• Visual breaks inserted where they aid comprehension
• Technical content: more frequent breaks (code, tables, lists)
• Conceptual content: longer prose passages acceptable if flow is maintained
• Long explanations broken up with lists, callouts, or code blocks where helpful
• White space used effectively between logical groups

• Appropriate callouts per section (2-4 for technical, fewer for conceptual)
• Callout types match content (💡 for insights, ⚠️ for warnings, etc.)
• Callouts not overused (losing impact)
• Callout formatting consistent throughout

• All code blocks have language specification (

  python, 

  javascript, etc.)
• Code includes explanatory comments
• Code is properly indented and formatted
• No orphaned code without surrounding explanation

• Tables used for comparisons and structured data
• Table headers are clear and descriptive
• Table formatting consistent (alignment, borders)
• No tables with only 1-2 rows (use list instead)

• Bullet points for unordered items
• Numbered lists for sequential steps
• Parallel grammatical structure in list items
• List items have consistent punctuation

• Bold used for key terms and emphasis
• Italics used for foreign terms and subtle emphasis

• inline code

  used for technical terms and commands
• No mixing of emphasis styles for same purpose

• ASCII diagrams properly aligned
• Diagrams have clear labels
• Complex relationships visualized, not just described

• Horizontal rules (---) used between major sections
• Visual breathing room between topics
• Consistent separator usage throughout

⚠️ TEXT WALL: [location] - Dense passage may benefit from visual break (consider context)
⚠️ MISSING CALLOUT: [section] - Key insight not highlighted (if appropriate for content type)
⚠️ UNSPECIFIED CODE: [line] - Code block missing language
⚠️ POOR TABLE: [location] - Consider converting to list
⚠️ INCONSISTENT EMPHASIS: [term] - Bold in some places, not others
⚠️ OVER-FORMATTED: [section] - Too many visual breaks disrupting narrative flow

Pass 6: Factual Accuracy (Truth Verification)

• All statistics match source data exactly
• All quotes are verbatim (no paraphrasing in quotes)
• All dates and names spelled correctly
• All technical specifications accurate
• No unsupported generalizations

1. Identify claim in draft
2. Locate cited source in research notes
3. Verify claim matches source exactly
4. Check for context (is claim misrepresented?)
5. Flag discrepancies for writer review

• High: 3+ authoritative sources agree
• Medium: 2 sources agree, or 1 highly authoritative source
• Low: Single source of moderate authority
• Unverified: No source found or sources conflict

Grammar and Style Rules Reference

Common Grammar Errors

• Wrong: "The team of editors review drafts."
• Correct: "The team of editors reviews drafts."

• Wrong: "The edit is complete, the draft is ready."
• Correct: "The edit is complete; the draft is ready."

• Wrong: "She only edited three chapters."
• Correct: "She edited only three chapters."

Style Preferences (Configurable per Project)

Readability Metrics

Flesch Reading Ease Score

• 90-100: Very Easy (5th grade) - Children's books
• 80-89: Easy (6th grade) - Conversational writing
• 70-79: Fairly Easy (7th grade) - General audience
• 60-69: Standard (8th-9th grade) - Business writing
• 50-59: Fairly Difficult (10th-12th grade) - Academic
• 40-49: Difficult - Advanced technical
• 30-39: Very Difficult - Highly specialized (compilers, physics, ML theory)
• Below 30: Expert only - Mathematical proofs, research papers

⚠️ Warning: Do NOT force higher Flesch scores on advanced technical content. Simplifying specialized terminology can reduce precision and accuracy. The goal is appropriate clarity for the intended audience.

• Shorten sentences (< 20 words average)
• Use simpler words (fewer syllables)
• Break complex sentences into multiple sentences
• Replace jargon with plain language

• Technical terminology is necessary for precision
• Audience expects domain vocabulary
• Simplification would lose meaning or accuracy

Passive Voice Percentage

1. Identify actor: WHO performs the action?
2. Rewrite with actor as subject
   • Passive: "The draft was reviewed by the editor."
   • Active: "The editor reviewed the draft."

Edit Summary Report Template

# Edit Summary: [Document Title]

**Edited**: [YYYY-MM-DD]
**Word Count**: [original] → [revised] ([+/- change])
**Total Changes**: [number]

## Changes by Category

### Grammar & Mechanics: [count]
### Citations: [count]
### Clarity & Flow: [count]
### Consistency: [count]
### Visual Formatting: [count]
### Factual Corrections: [count]

## Quality Metrics

| Metric | Before | After | Target | Status |
|--------|--------|-------|--------|--------|
| Flesch Reading Ease | [score] | [score] | [per content type] | ✅/❌ |
| Citation Coverage | [%] | [%] | 100% | ✅/❌ |
| Passive Voice % | [%] | [%] | <20% | ✅/❌ |
| Avg Sentence Length | [words] | [words] | [per content type] | ✅/❌ |
| Text Walls Fixed | [count] | 0 | 0 | ✅/❌ |
| Callouts Per Section | [avg] | [avg] | 2-4 | ✅/❌ |
| Code Blocks w/ Language | [%] | [%] | 100% | ✅/❌ |

**Content Type**: [general/business/intro-tech/advanced-tech/specialized]

## Visual Formatting Summary
- **Callouts added**: [count] (💡: [n], ⚠️: [n], 🎯: [n], etc.)
- **Tables created**: [count]
- **Lists converted**: [count] (from run-on sentences)
- **ASCII diagrams added**: [count]
- **Text walls broken up**: [count]

## Issues Requiring Author Review
- [Unverifiable claims, technical accuracy questions]

## Recommendations
- [Patterns to watch in future writing]

Common Editing Pitfalls

1. Over-Editing: Edit for correctness and clarity, not personal preference
2. Missing Context: Read surrounding paragraphs before making changes
3. Inconsistent Application: Use Grep to find ALL instances, apply rule uniformly
4. Citation Overload: Distinguish common knowledge from factual claims
5. Ignoring Readability: Balance formal correctness with reader comprehension

Quality Assurance

• All six editorial passes completed
• 100% citation coverage verified
• Readability target achieved (Flesch > 60)
• Consistency issues resolved
• Visual formatting standards met
• Edit summary report generated
• Flagged issues documented for author