# 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:
1. Repeated/overused phrases across the manuscript
2. Continuity errors, timeline inconsistencies, and world-building contradictions
3. 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:
  1. Read target chapters fully
  2. Extract candidate phrases: multi-word expressions (2-4 words) appearing 3+ times within target range
  3. Also flag distinctive single words used excessively (adverbs, specific adjectives)
  4. For each candidate, use Grep to count occurrences across ALL chapter files in the book
  5. 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:
  1. Read chapters with a literary editor's eye
  2. Identify repetitive sentence structures (not just repeated words)
  3. Flag overused transitions, beats, and narration patterns
  4. Distinguish intentional voice patterns (Phelan's established mannerisms per CLAUDE.md) from authorial habits
  5. 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:
  1. **Timeline**: Bell references, day-of-week, elapsed time vs. `timeline-book{N}.md`
  2. **Characters**: Name spelling, knowledge consistency, physical descriptions vs. character files
  3. **World-building**: Currency amounts vs. `economy.md`, location details vs. location files, magic usage vs. runic-flow rules
  4. **Plot threads**: Threads from earlier chapters (per story summary) referenced appropriately? Dangling threads?
  5. **Internal consistency**: Facts within the target range don't contradict each other
- 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:
  1. **Premise & conflict**: Central conflict clear and advancing? Stakes escalating?
  2. **Character arcs**: Phelan's growth visible? Supporting cast serving their functions?
  3. **Foreshadowing**: Seeds planted and paid off? Setups subtle enough?
  4. **POV consistency**: Every paragraph sounds like Phelan? No slips into omniscient?
  5. **Pacing**: Action/investigation/quiet beats distributed well?
  6. **World-building integration**: Detail woven into action or dumped as exposition?
  7. **The Noise convention**: Parenthetical tangents at right frequency and doing narrative work?
  8. **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:
1. `/manuscript-analysis 1 1-3` — small range, should complete with all 4 intermediate + 1 consolidated report
2. Check that phrase index contains Grep counts across all 21 chapters (not just 1-3)
3. Check that continuity report references timeline and character files
4. Check that story craft report addresses all 8 analysis categories
5. Verify consolidated report has severity tiers and deduplication
