Revising Chapters

Makes targeted improvements to chapters based on user feedback.

When to use this skill

• •User says "revise chapter X"
• •User provides feedback: "Chapter 3 needs more examples"
• •User requests changes: "Make chapter 2 more conversational"
• •User wants rewrites: "Rewrite the opening of chapter 5"
• •User mentions length: "Expand chapter 4"

What this skill does

1. •Loads the current chapter
2. •Reads outline for context (theme, purpose)
3. •Reads voice-profile for consistency
4. •Applies requested changes
5. •Git commits with descriptive message

Prerequisites

Must exist:

• •The chapter file being revised
• •outline.md (for theme/context)

If chapter doesn't exist:

I don't see /chapters/[number]-[title].md. 
Available chapters: [list existing chapter files]

Which chapter did you mean?

Revision types

Full rewrite

Trigger: "Revise chapter 3 based on this feedback: [notes]"

Process:

1. •Read current chapter
2. •Read all feedback/notes
3. •Understand what needs to change
4. •Rewrite chapter incorporating feedback
5. •Maintain theme alignment and voice

Targeted fix

Trigger: "Strengthen the opening of chapter 5"

Process:

1. •Read current chapter
2. •Focus only on specified section
3. •Improve that section
4. •Keep rest of chapter unchanged

Tone adjustment

Trigger: "Make chapter 2 more conversational"

Process:

1. •Read current chapter + voice-profile
2. •Adjust formality/style throughout
3. •Keep content/structure same
4. •Make it match requested tone

Content addition

Trigger: "Add more examples to chapter 4"

Process:

1. •Read current chapter
2. •Identify places needing examples
3. •Add 2-3 concrete examples
4. •Maintain flow and transitions

Length adjustment

Trigger: "Expand chapter 6" or "Condense chapter 2"

Process:

1. •Read current chapter
2. •Expand: Add detail, examples, explanation
3. •Condense: Remove redundancy, tighten prose
4. •Maintain key points and theme alignment

Process

Step 1: Understand the request

Clarify if needed:

• •Vague: "Revise chapter 3" → Ask: "What would you like me to change?"
• •Clear: "Add statistics to support the claims in chapter 3" → Proceed

Step 2: Load context

Read:

1. •Current chapter file
2. •outline.md (theme, chapter purpose)
3. •voice-profile.md if exists
4. •Adjacent chapters if needed for continuity

Step 3: Apply changes

Make the requested changes while maintaining:

• •Theme alignment
• •Voice consistency
• •Key points from outline
• •Natural flow

If change would hurt theme alignment, flag it:

Note: Making chapter 4 entirely about [X] would weaken its connection to 
the theme of [Y]. Consider: [alternative approach]

Step 4: Handle new research gaps

If revision introduces new gaps, mark them:

[RESEARCH: Need case study showing X | severity: MEDIUM]

Step 5: Git commit

Commit message should describe what changed:

git add chapters/[number]-[title].md
git commit -m "Revision: Chapter [number] - [brief description]"

Good commit messages:

• •"Revision: Chapter 3 - Added examples and data"
• •"Revision: Chapter 5 - Rewrote opening for stronger hook"
• •"Revision: Chapter 2 - Made tone more conversational"

Bad commit messages:

• •"Revision: Chapter 3" (not specific)
• •"Updates" (too vague)
• •"Fixed stuff" (unhelpful)

Examples

Example 1: Feedback-based revision

User: "Revise chapter 2. The feedback from my editor is: needs more concrete examples, and the transition to section 3 is abrupt."

Process:

1. •Read chapter 2
2. •Identify where examples would help
3. •Add 2-3 concrete examples
4. •Smooth transition to section 3
5. •Git commit: "Revision: Chapter 2 - Added examples and improved transition"

Example 2: Tone adjustment

User: "Make chapter 4 more data-driven. Right now it's too anecdotal."

Process:

1. •Read chapter 4
2. •Identify anecdotal sections
3. •Replace some stories with statistics/studies
4. •Keep some anecdotes for balance
5. •Git commit: "Revision: Chapter 4 - Shifted to more data-driven approach"

Example 3: Length expansion

User: "Chapter 1 is only 800 words. Expand it to hit closer to 1,500."

Process:

1. •Read chapter 1 + outline to see key points
2. •Add depth: more explanation, examples, or setup
3. •Don't pad - add substance
4. •Check: does it feel natural or forced?
5. •Git commit: "Revision: Chapter 1 - Expanded with additional depth"

Example 4: Structural change

User: "Move the framework explanation from chapter 3 to chapter 2, and adjust both chapters accordingly."

Process: This affects multiple chapters:

1. •Extract framework section from chapter 3
2. •Integrate into chapter 2 (find best placement)
3. •Adjust chapter 3 to flow without that section
4. •Update transitions in both
5. •Git commit BOTH chapters:

git add chapters/02-*.md chapters/03-*.md
git commit -m "Revision: Chapters 2-3 - Moved framework explanation to chapter 2"

Edge cases

Requested change conflicts with theme:

Making this change would weaken chapter [X]'s alignment with the theme.

Current theme: [statement]
Requested change: [description]
Conflict: [explanation]

Options:
1. Modify the change to maintain alignment: [suggestion]
2. Adjust the theme (requires reviewing all chapters)
3. Keep chapter as-is

What would you prefer?

Revision requires information not available:

To make this revision well, I'd need:
- [Specific info needed]
- [Other info needed]

Should I:
1. Make the revision with placeholder [RESEARCH: ...] markers
2. Wait until you provide this information

Unclear which chapter:

Which chapter should I revise?
Current chapters: [list from /chapters/ directory]

Multiple conflicting feedback points:

I see two pieces of feedback that conflict:
1. [Feedback A]
2. [Feedback B]

Which should take priority, or how should I balance them?

Quality standards

Revised chapters should:

• •✓ Address the specific feedback/request
• •✓ Maintain theme alignment
• •✓ Match voice profile
• •✓ Keep key points from outline
• •✓ Have natural flow and transitions
• •✓ Not introduce new problems

Collaboration with other skills

After revising:

• •Use check-theme-alignment if revision was substantial
• •Use track-research-gaps if new gaps were added
• •Consider revising adjacent chapters if flow was affected

Before revising:

• •User might have used check-theme-alignment to identify issues
• •Revision addresses alignment problems flagged

Files modified

• •/chapters/[number]-[title].md - The revised chapter
• •Sometimes multiple chapter files if structural changes

Best practices

Do:

• •Ask for clarification if request is vague
• •Flag when changes would hurt alignment
• •Make substantive improvements, not just word count padding
• •Maintain consistency with voice profile
• •Test whether revised section flows naturally

Don't:

• •Make changes you're not asked to make
• •Sacrifice theme alignment for other goals
• •Add fluff to hit word counts
• •Change voice significantly unless requested
• •Revise more chapters than requested without asking