195 lines
8.5 KiB
Markdown
195 lines
8.5 KiB
Markdown
# 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
|