8.5 KiB
Manuscript Analysis Skill — Design Spec
Date: 2026-03-10 Purpose: Reusable skill to analyze manuscript chapters for repeated phrases, continuity errors, and story craft quality.
Context
Book 1 of The Shade Series is complete at ~104K words across 21 chapters. Before publication and during future book development, the author needs repeatable quality checks that catch:
- Repeated/overused phrases across the manuscript
- Continuity errors, timeline inconsistencies, and world-building contradictions
- Story craft issues (pacing, character arcs, foreshadowing, POV consistency)
The challenge: the full manuscript exceeds what fits in a single context window. This skill solves that with a multi-agent pipeline where each agent gets a fresh context window and a focused task.
Invocation
/manuscript-analysis [book-number] [chapter-range]
Examples:
/manuscript-analysis 1 1-5— analyze chapters 1-5 of book 1/manuscript-analysis 1 16-21— analyze chapters 16-21/manuscript-analysis 2 1-7— future book 2
The skill parses the book number and chapter range, validates that the chapter files exist (e.g., chapters/book1/ch01-final.md through ch05-final.md), and creates the output directory if needed.
Architecture: Multi-Agent Pipeline
The orchestrator (main session) dispatches subagents via the Agent tool. Each subagent gets a clean context window. The orchestrator does NOT perform analysis itself — it coordinates and aggregates.
/manuscript-analysis 1 1-5
|
ORCHESTRATOR
|
Phase 1: PHRASE ANALYSIS
|-- Agent 1A: Grep-based phrase indexing (target chapters + Grep across full book)
|-- Agent 1B: Literary phrase analysis (target chapters + index from 1A)
|
Phase 2: CONTINUITY CHECK
|-- Agent 2A: Cross-reference target chapters against all reference docs
|-- (Agent 2B: if range > 7 chapters, split the work)
|
Phase 3: STORY CRAFT
|-- Agent 3A: Narrative analysis against story summary + outline
|
Phase 4: AGGREGATION
|-- Orchestrator reads intermediate reports, writes consolidated report
Why Subagents?
Each agent gets a fresh ~200K token context window. Without subagents, analysis of even 5 chapters plus reference docs would consume the entire session context, degrading output quality and preventing further work.
Why Grep for Phrase Indexing?
The Grep tool searches the filesystem directly — it does not load files into the context window. This lets Agent 1A query the full 104K-word manuscript for phrase frequencies without exceeding its context budget. The tradeoff: Grep only catches exact string matches, not semantic repetition. Agent 1B handles the semantic/structural analysis.
Phase Details
Phase 1: Repeated Phrase Analysis
Agent 1A — Phrase Indexer
- Loads: target chapter files only (~33K tokens for 5 chapters)
- Process:
- Read target chapters fully
- Extract candidate phrases: multi-word expressions (2-4 words) appearing 3+ times within target range
- Also flag distinctive single words used excessively (adverbs, specific adjectives)
- For each candidate, use Grep to count occurrences across ALL chapter files in the book
- Record: phrase, count in target range, count in full book, which chapters contain it
- Output:
notes/analysis/book{N}-phrase-index-ch{XX}-{YY}.md - Context budget: ~40K tokens
Agent 1B — Phrase Analyst
- Loads: target chapter files + phrase index from 1A + CLAUDE.md voice guidelines
- Process:
- Read chapters with a literary editor's eye
- Identify repetitive sentence structures (not just repeated words)
- Flag overused transitions, beats, and narration patterns
- Distinguish intentional voice patterns (Phelan's established mannerisms per CLAUDE.md) from authorial habits
- Note phrases that work as intentional callbacks vs. unintentional repetition
- Output:
notes/analysis/book{N}-phrase-analysis-ch{XX}-{YY}.md - Context budget: ~45K tokens
Phase 2: Continuity & Consistency Check
Agent 2A — Continuity Checker
- Loads: target chapters + story summary + timeline + exploits log + relevant character files + economy + location files
- Checks:
- Timeline: Bell references, day-of-week, elapsed time vs.
timeline-book{N}.md - Characters: Name spelling, knowledge consistency, physical descriptions vs. character files
- World-building: Currency amounts vs.
economy.md, location details vs. location files, magic usage vs. runic-flow rules - Plot threads: Threads from earlier chapters (per story summary) referenced appropriately? Dangling threads?
- Internal consistency: Facts within the target range don't contradict each other
- Timeline: Bell references, day-of-week, elapsed time vs.
- Output:
notes/analysis/book{N}-continuity-ch{XX}-{YY}.md - Context budget: ~85K tokens (for 5 chapters)
Splitting rule: If chapter range > 7 chapters, split into two agents (2A + 2B), each handling half the range. Both load the full reference docs.
Phase 3: Story Craft Feedback
Agent 3A — Story Craft Analyst
- Loads: target chapters + story summary + book outline + CLAUDE.md + book-specific CLAUDE.md
- Analyzes:
- Premise & conflict: Central conflict clear and advancing? Stakes escalating?
- Character arcs: Phelan's growth visible? Supporting cast serving their functions?
- Foreshadowing: Seeds planted and paid off? Setups subtle enough?
- POV consistency: Every paragraph sounds like Phelan? No slips into omniscient?
- Pacing: Action/investigation/quiet beats distributed well?
- World-building integration: Detail woven into action or dumped as exposition?
- The Noise convention: Parenthetical tangents at right frequency and doing narrative work?
- What's working well: Specific callouts of strong passages and techniques
- Output:
notes/analysis/book{N}-storycraft-ch{XX}-{YY}.md - Context budget: ~75K tokens
Phase 4: Aggregation
The orchestrator reads all intermediate reports and writes a consolidated final report:
- Organized by severity: Critical (plot holes, continuity breaks) > Important (repeated phrases, voice slips) > Suggestions (craft improvements)
- Deduplicates where multiple agents flagged the same issue
- Summary at top with counts per category
- Output:
notes/analysis/book{N}-analysis-ch{XX}-{YY}.md
Context Budget Summary (5-chapter range)
| Agent | Chapter Text | Reference Docs | Total |
|---|---|---|---|
| 1A (Phrase Indexer) | ~33K tokens | minimal | ~40K |
| 1B (Phrase Analyst) | ~33K tokens | ~10K | ~45K |
| 2A (Continuity) | ~33K tokens | ~50K | ~85K |
| 3A (Story Craft) | ~33K tokens | ~40K | ~75K |
All well within the ~200K token window per agent.
Output Structure
notes/analysis/
book1-phrase-index-ch01-05.md # Raw phrase frequency data
book1-phrase-analysis-ch01-05.md # Literary phrase analysis
book1-continuity-ch01-05.md # Continuity findings
book1-storycraft-ch01-05.md # Story craft findings
book1-analysis-ch01-05.md # Final consolidated report
Previous analysis files are overwritten on re-run (same book/range).
Reference Files Used
| File | Used By | Purpose |
|---|---|---|
chapters/book{N}/chXX-final.md |
All agents | Source manuscript text |
world/story-summary-book{N}.md |
Phases 2, 3 | Narrative context proxy for chapters not being directly analyzed |
world/timeline-book{N}.md |
Phase 2 | Timeline consistency reference |
world/magic/exploits-log.md |
Phase 2 | Magic system consistency |
world/magic/runic-flow-rules.md |
Phase 2 | Magic system rules |
world/economy.md |
Phase 2 | Currency/pricing reference |
world/locations/*.md |
Phase 2 | Location detail reference |
characters/*.md |
Phase 2 | Character detail reference |
outline/book{N}-outline.md |
Phase 3 | Intended vs. actual pacing |
CLAUDE.md |
Phases 1B, 3 | Voice guidelines, style rules |
chapters/book{N}/CLAUDE.md |
Phase 3 | Book-specific premise/themes |
Skill File Location
~/.claude/skills/manuscript-analysis/SKILL.md
Verification
After implementation, test with:
/manuscript-analysis 1 1-3— small range, should complete with all 4 intermediate + 1 consolidated report- Check that phrase index contains Grep counts across all 21 chapters (not just 1-3)
- Check that continuity report references timeline and character files
- Check that story craft report addresses all 8 analysis categories
- Verify consolidated report has severity tiers and deduplication