first commit

2026-04-06 15:28:27 -05:00
commit 026419736d
4 changed files with 678 additions and 0 deletions
--- a/chapter-workflow/SKILL.md
+++ b/chapter-workflow/SKILL.md
@@ -0,0 +1,146 @@
+---
+name: chapter-workflow
+description: Use when starting a new chapter, resuming chapter drafting, or moving to the next stage of chapter development for The Shade Series. Invoke with a chapter number argument, e.g. /chapter-workflow 3
+---
+
+# Chapter Workflow
+
+5-stage pipeline for developing chapters. Invoke with chapter number: `/chapter-workflow 3`
+
+## Stage Flow
+
+```dot
+digraph chapter_flow {
+    rankdir=TB;
+    node [shape=box];
+
+    detect [label="Detect book + stage\nfrom existing files" shape=diamond];
+    seed [label="Stage 1: Seed\nConfirm chXX-input.md exists\nand has content"];
+    breakdown [label="Stage 2: Scene Breakdown\nRead input + summary + outline\nPropose scene plan"];
+    draft [label="Stage 3: Draft\nWrite full chapter\ninto chXX-draft.md"];
+    revision [label="Stage 4: Review\nAuthor edits, then Claude reviews\nclarity/grammar/flow"];
+    continuity [label="Stage 5: Continuity\nUpdate world/character files\n+ story summary + timeline"];
+
+    detect -> seed [label="no input file"];
+    detect -> breakdown [label="input exists, no draft"];
+    detect -> draft [label="draft in progress"];
+    detect -> revision [label="draft complete"];
+    detect -> continuity [label="final exists"];
+
+    seed -> breakdown;
+    breakdown -> draft;
+    draft -> revision;
+    revision -> continuity;
+}
+```
+
+## On Invoke
+
+Parse chapter number from args (default: ask). Set `XX` = zero-padded number.
+
+### Detect Book Number
+
+Determine which book we're working on by checking the chapter directory path:
+- Look for `chapters/book{N}/chXX-input.md` — the `{N}` is the book number
+- If the user has a `chXX-input.md` open in the IDE, derive the book number from its path
+- If ambiguous, check which `chapters/book{N}/` directories exist and ask the user
+- Set `BOOK` = detected book number (e.g., `1`, `2`, `3`)
+
+All subsequent file references use `book{BOOK}` instead of hardcoded `book1`.
+
+### Key Context Files (per book)
+
+These files provide continuity context. **Read the story summary and timeline instead of re-reading prior chapter drafts:**
+
+| File | Purpose |
+|------|---------|
+| `world/story-summary-book{BOOK}.md` | Running summary of all prior chapters — characters, events, plot threads, financial state. **Primary context source.** |
+| `world/timeline-book{BOOK}.md` | Bell/time references, day-of-week tracking, elapsed time. **Check before writing any time reference.** |
+| `chapters/book{BOOK}/CLAUDE.md` | Book-specific premise, themes, milestone beats |
+| `outline/book{BOOK}-outline.md` | Chapter-by-chapter outline |
+| `world/magic/exploits-log.md` | All exploits used (cross-book) |
+
+### Detect Stage
+
+Check which files exist in `chapters/book{BOOK}/`:
+
+| Files Present | Stage |
+|---------------|-------|
+| No `chXX-input.md` | Create from template, ask author to fill it |
+| `chXX-input.md` only | Stage 2: Scene Breakdown |
+| `chXX-input.md` + partial `chXX-draft.md` | Stage 3: Resume/complete draft |
+| `chXX-input.md` + complete `chXX-draft.md` | Stage 4: Author edits, then review |
+| `chXX-final.md` exists | Stage 5: Continuity update |
+
+## Stage 1: Seed
+
+If `chXX-input.md` doesn't exist, create it from `chapters/book{BOOK}/chapter-input-template.md` with the chapter number filled in. Tell the author to fill in their notes and re-invoke.
+
+If `chXX-input.md` exists but sections are empty (only HTML comments), tell the author it needs content before proceeding.
+
+## Stage 2: Scene Breakdown
+
+Read these files for context:
+- `chapters/book{BOOK}/chXX-input.md` — author's notes for this chapter
+- `world/story-summary-book{BOOK}.md` — **prior chapter context (DO NOT re-read full chapter drafts)**
+- `world/timeline-book{BOOK}.md` — timeline and time references
+- `outline/book{BOOK}-outline.md` — chapter outline
+- `chapters/book{BOOK}/CLAUDE.md` — book-specific instructions
+- `world/magic/exploits-log.md` — exploits used so far
+- Relevant character files from `characters/` (check story summary for which characters are active)
+
+Propose a scene-by-scene plan:
+- Number of scenes with estimated word counts
+- What each scene accomplishes
+- Where input dialog and character moments slot in
+- Opening hook and closing beat
+- Timeline placement (what day, what bells) — cross-reference with `timeline-book{BOOK}.md`
+
+**Wait for author approval before proceeding to Stage 3.**
+
+## Stage 3: Draft
+
+Write the full chapter in one pass based on the approved scene plan. Save to `chXX-draft.md`.
+
+**Before drafting:** Re-read the story summary and timeline to ensure continuity. Do NOT re-read full prior chapter drafts — the summary contains everything needed.
+
+**Process:**
+1. Write all scenes sequentially into a single complete chapter draft
+2. Save the entire draft to `chXX-draft.md`
+3. Tell the author the draft is ready for their editing
+
+**Rules during drafting:**
+- First-person, past tense, Phelan's voice (dry wit, ADD tangents, precise observations)
+- KDP formatting from first draft (em dashes `—`, smart quotes, `* * *` scene breaks)
+- Flag continuity concerns: `[CONTINUITY FLAG: note]`
+- Target 3,000–5,000 words total
+- End with resolved beat or micro-hook
+- All time references (bells, days, day-of-week) must match `timeline-book{BOOK}.md`
+
+**After saving:** Tell the author the draft is in `chXX-draft.md` and to edit it directly. When they're satisfied with their edits, they should re-invoke `/chapter-workflow XX` for the final review.
+
+## Stage 4: Review
+
+The author has edited `chXX-draft.md`. Now perform a final review focused on:
+
+1. **Clarity** — are descriptions, actions, and dialog clear and unambiguous?
+2. **Grammar** — correct spelling, punctuation, tense consistency, subject-verb agreement
+3. **Chapter flow** — does the chapter read smoothly from opening to close? Are transitions between scenes natural?
+4. **Sentence flow** — varied sentence length, no awkward constructions, rhythm feels right for each scene type (clipped in action, discursive in investigation, slower in quiet moments)
+5. **Voice consistency** — every paragraph sounds like Phelan
+6. **Continuity** — cross-check against `world/story-summary-book{BOOK}.md` and `world/timeline-book{BOOK}.md` for conflicts with established canon
+7. **KDP formatting** — em dashes, smart quotes, scene breaks, structure
+
+**Output format:** Present findings organized by category. For each issue, quote the relevant text and suggest a fix. After author approval of any changes, **rename** `chXX-draft.md` to `chXX-final.md` using `mv` — do NOT rewrite the file contents.
+
+## Stage 5: Continuity Update
+
+Update project files with new canon from the chapter:
+- `world/story-summary-book{BOOK}.md` — **add chapter summary, update character tracker, plot threads, financial ledger, and world facts**
+- `world/timeline-book{BOOK}.md` — **add timeline entries for new chapter (bells, days, elapsed time)**
+- `world/magic/exploits-log.md` — new exploits
+- `characters/` — new or changed characters
+- `world/locations/` — new locations
+- `world/` — new world facts
+
+Report what was updated.
--- a/implementing-roadmap-phases/SKILL.md
+++ b/implementing-roadmap-phases/SKILL.md
@@ -0,0 +1,205 @@
+---
+name: implementing-roadmap-phases
+description: Use when asked to review a roadmap document and implement a specific phase or phase range, e.g. "implement phase 3" or "implement phases 1-3 from the roadmap"
+---
+
+# Implementing Roadmap Phases
+
+## Overview
+
+Structured workflow for implementing phases from roadmap documents. Ensures clarifying questions are always asked before coding, and the roadmap is always updated after each phase completes.
+
+**Core principle:** Never implement blind — always parse, explore, ask, then build. Never leave the roadmap stale — always update after completing a phase.
+
+## When to Use
+
+- User says "implement phase N" or "implement phases N-M" referencing a roadmap doc
+- User asks to "review this roadmap and build the next phase"
+- Any task driven by a phased planning document
+
+**When NOT to use:** One-off feature requests not tied to a roadmap document.
+
+## Workflow
+
+```dot
+digraph roadmap_flow {
+    rankdir=TB;
+    parse [label="1. Parse Roadmap" shape=box];
+    explore [label="2. Explore Referenced Patterns" shape=box];
+    ask [label="3. Ask Clarifying Questions" shape=box];
+    brief [label="4. Write Implementation Brief" shape=box style=bold];
+    compact [label="4.5. Clear Context\n(/compact + re-read brief)" shape=box style=bold color=blue];
+    implement [label="5. Dispatch Implementation\n(fresh context)" shape=box style=bold];
+    verify [label="6. Verify & Fix" shape=box style=bold color=red];
+    pass [label="All checks\npass?" shape=diamond];
+    fix [label="Fix errors\n(max 3 attempts)" shape=box];
+    escalate [label="Escalate to user" shape=box];
+    update [label="7. Update Roadmap" shape=box];
+    more [label="More phases\nin range?" shape=diamond];
+    done [label="Done" shape=doublecircle];
+
+    parse -> explore -> ask -> brief -> compact -> implement -> verify -> pass;
+    pass -> update [label="yes"];
+    pass -> fix [label="no"];
+    fix -> verify [label="retry"];
+    fix -> escalate [label="max retries"];
+    escalate -> update [label="user resolves"];
+    update -> more;
+    more -> parse [label="yes — next phase"];
+    more -> done [label="no"];
+}
+```
+
+### Step 1: Parse the Roadmap
+
+Read the full document. Identify:
+- Target phase(s) and their requirements
+- Conventions section (naming, patterns, tech choices)
+- Dependency graph (what prior phases built that this phase needs)
+- Referenced patterns (e.g. "Follow `scans.py` pattern")
+- For ranges (e.g. "phases 1-3"): validate sequential order, note inter-phase dependencies
+
+### Step 2: Explore Referenced Patterns
+
+Read existing code files mentioned in implementation notes. Understand:
+- File structure and naming conventions used in referenced examples
+- How similar features were built (routes, services, DB queries, templates)
+- Conventions section requirements applied to real code
+
+### Step 3: Ask Clarifying Questions (MANDATORY)
+
+**Always ask at least one round of questions before implementing.** Categories:
+
+- **Ambiguous requirements** — Anything in the phase spec that could be interpreted multiple ways
+- **Open design decisions** — Choices the roadmap left to the implementer
+- **Scope confirmation** — "Phase says X; should I also handle Y?"
+- **Dependency status** — "Phase references table Z from Phase 2; is that already migrated?"
+
+Use `AskUserQuestion` tool with structured options where possible.
+
+### Step 4: Write Implementation Brief (MANDATORY)
+
+**Purpose:** Distill everything from steps 1-3 into a concise brief so implementation can run with clean context.
+
+After clarifying questions are answered, write a brief to a temporary file (e.g. `/tmp/phase-N-brief.md`) containing:
+
+1. **Phase goal** — One sentence summary of what to build
+2. **Files to create/modify** — Exact paths from the roadmap
+3. **Conventions** — Naming patterns, tech choices, coding patterns to follow
+4. **Design decisions** — Answers from clarifying questions
+5. **Reference patterns** — Key file paths explored in Step 2 that the implementer should read (NOT the content — just the paths, so the subagent reads them fresh)
+6. **Constraints** — Anything that must be true (e.g. "all queries filter by organization_id")
+
+**Keep the brief under 100 lines.** This is the ONLY context the implementation subagent receives.
+
+### Step 4.5: Clear Context (MANDATORY)
+
+**Purpose:** Steps 1-3 read many files and fill the context with exploration noise. The brief captures everything needed — the exploration context is now dead weight that will degrade implementation quality.
+
+**After writing the brief, you MUST:**
+
+1. Tell the user: "Planning complete. Brief written to `/tmp/phase-N-brief.md`. Compacting context before implementation."
+2. Run `/compact` to compress the conversation history
+3. After compaction, **re-read only the brief file** (`/tmp/phase-N-brief.md`) to restore working context
+4. Then proceed to Step 5
+
+**Why this matters:** Without compaction, the main agent carries thousands of tokens of file contents, dead-end explorations, and question/answer exchanges that are already distilled into the brief. This pollutes the context for verification (Step 6) and roadmap updates (Step 7), and can cause the agent to lose track of what was actually decided.
+
+**Do NOT skip this step.** The brief is the single source of truth after planning. Everything else is noise.
+
+### Step 5: Dispatch Implementation (Fresh Context)
+
+**Use the Task tool** to spawn a subagent for implementation. This gives the implementer a clean context window free of exploration noise.
+
+The Task prompt should:
+- Reference the brief file: "Read `/tmp/phase-N-brief.md` for full requirements"
+- Reference the roadmap file for additional detail if needed
+- List the specific files to create/modify
+- Instruct the subagent to read the reference pattern files listed in the brief before writing code
+
+**For multi-phase ranges:** Complete Step 6 (update roadmap) before starting the next phase's Step 1.
+
+**Subagent type:** Use `general-purpose` for phases that involve multiple file types (API + UI + migrations). Use `Bash` only for pure migration/script phases.
+
+### Step 6: Verify & Fix (MANDATORY)
+
+**Purpose:** Catch runtime errors, test failures, and schema mismatches before marking the phase complete. Never update the roadmap for broken code.
+
+**Run these checks in order (stop at first failure):**
+
+1. **App loads** — Run the app import/startup check (e.g. `uv run python -c "from src.main import get_app; app = get_app()"`) for each affected service
+2. **Tests pass** — Run the test suite for each affected service (e.g. `uv run pytest`)
+3. **Smoke test** — If the phase added API routes, verify they're registered (check route list or import the router)
+
+**If any check fails:**
+
+1. Read the full error output — identify root cause (missing column default, bad import, wrong type, etc.)
+2. Fix the issue directly — don't re-dispatch to a subagent for small fixes
+3. Re-run the failing check to confirm the fix
+4. Continue to the next check
+
+**Retry limit:** Maximum 3 fix attempts per check. If a check still fails after 3 attempts:
+- Summarize what was tried and what the error is
+- Show the user the error output
+- Ask the user how to proceed (skip, manual fix, or abort)
+
+**What NOT to fix in this step:**
+- Pre-existing lint warnings (ruff I001, E402, etc.) — only fix lint errors in new code
+- Pre-existing test failures — only new failures caused by this phase
+
+### Step 7: Update the Roadmap (MANDATORY)
+
+Mark the completed phase with a checkmark and replace its content with a compact summary using this template:
+
+```markdown
+### Phase N: Title ✅
+
+**Completed:** YYYY-MM-DD
+
+**Summary:** [1-2 sentences describing what was built]
+
+**Key files:**
+- `path/to/file.py` — [role]
+
+**Endpoints created:** (if applicable)
+- `POST /resource` — [purpose]
+- `GET /resource/{id}` — [purpose]
+
+**Key details:**
+- [Implementation decisions, enum values, constraints, patterns applied]
+- [Anything future phases need to know]
+```
+
+Preserve enough detail that future phases can reference what was built without reading all the code.
+
+## Red Flags — STOP If You Catch Yourself Thinking This
+
+| Thought | Reality |
+|---------|---------|
+| "The requirements are clear, I'll skip questions" | Requirements always have ambiguity. Ask at least one round. |
+| "I'll update the roadmap later" | You'll forget. Update immediately after each phase. |
+| "I'll implement all phases first, then update" | Multi-phase ranges require update between each. One at a time. |
+| "The roadmap update is just bookkeeping" | Future phases depend on accurate roadmap state. It's not optional. |
+| "I already know the codebase patterns" | Read the referenced files anyway. Patterns evolve. |
+| "This phase is simple, no questions needed" | Simple phases still have scope and design decisions. Ask. |
+| "The brief is extra overhead, I'll just implement" | The brief IS the value — it forces you to crystallize decisions and gives the subagent clean context. |
+| "I can implement in the same context" | Exploration context pollutes implementation. Fresh context = fewer mistakes. |
+| "I don't need to compact, the brief is enough" | The brief helps the subagent. Compaction helps YOU — verification and roadmap updates need clean context too. |
+| "The subagent can just read the roadmap" | The roadmap has ambiguity — that's why you asked questions. The brief captures resolved decisions. |
+| "The subagent said it's done, must be fine" | Subagents don't always verify. Run the checks yourself. |
+| "It compiled so it works" | Import success != runtime success. Run tests and smoke checks. |
+| "I'll skip verification, it's a small phase" | Small phases cause NOT NULL violations and broken DI. Always verify. |
+| "The error is pre-existing, not my problem" | Confirm it's pre-existing before ignoring. Check git diff. |
+
+## Quick Reference
+
+| Step | Required? | Key Action |
+|------|-----------|------------|
+| 1. Parse | Yes | Read full doc, identify target + dependencies |
+| 2. Explore | Yes | Read referenced code files |
+| 3. Ask | **MANDATORY** | At least one round of clarifying questions |
+| 4. Brief | **MANDATORY** | Write implementation brief to `/tmp/phase-N-brief.md` |
+| 4.5. Clear Context | **MANDATORY** | Run `/compact`, then re-read only the brief file |
+| 5. Implement | Yes | Dispatch subagent via Task tool with fresh context |
+| 6. Verify & Fix | **MANDATORY** | App loads + tests pass + smoke test; fix loop with 3 retries |
+| 7. Update | **MANDATORY** | Replace phase content with summary template |
--- a/manuscript-analysis/SKILL.md
+++ b/manuscript-analysis/SKILL.md
@@ -0,0 +1,251 @@
+---
+name: manuscript-analysis
+description: Use when analyzing manuscript chapters for repeated phrases, continuity errors, and story craft quality. Invoke with book number and chapter range, e.g. /manuscript-analysis 1 1-5
+---
+
+# Manuscript Analysis
+
+Multi-agent pipeline for analyzing manuscript chapters. Invoke with book number and chapter range: `/manuscript-analysis 1 1-5`
+
+## On Invoke
+
+Parse args: first arg = book number (`BOOK`), second arg = chapter range (`XX-YY`). If missing, ask the user.
+
+Set `XX` = start chapter (zero-padded), `YY` = end chapter (zero-padded).
+
+### Validate
+
+1. For each chapter in range, verify `chapters/book{BOOK}/ch{NN}-final.md` exists
+2. If any are missing, report which and stop
+3. Create `notes/analysis/` directory if it doesn't exist
+
+### File Naming
+
+All output files use: `notes/analysis/book{BOOK}-{type}-ch{XX}-{YY}.md`
+
+Where `{XX}` and `{YY}` are zero-padded to 2 digits (e.g., `ch01-05`, `ch16-21`).
+
+---
+
+## Phase 1: Phrase Analysis
+
+Run two agents **sequentially** (1B depends on 1A's output).
+
+### Agent 1A — Phrase Indexer
+
+Dispatch via Agent tool with `subagent_type: "general-purpose"`:
+
+```
+prompt: |
+  You are a phrase indexer for a manuscript analysis pipeline. Your job is to find repeated phrases across chapter files.
+
+  **Target chapters:** Read these files fully:
+  {list each chapters/book{BOOK}/ch{NN}-final.md in the range XX to YY}
+
+  **Task:**
+  1. Read all target chapter files
+  2. Extract candidate phrases: multi-word expressions (2-4 words) that appear 3 or more times within the target range. Also flag distinctive single words used excessively (adverbs, specific adjectives — not common words like "the", "was", "had", "said").
+  3. For EACH candidate phrase, use the Grep tool to count occurrences across ALL chapter files in chapters/book{BOOK}/ (not just the target range). Use: Grep with pattern="{phrase}" path="chapters/book{BOOK}/" output_mode="count"
+  4. Record results in a markdown table with columns: Phrase | Count in Ch {XX}-{YY} | Count in Full Book | Chapters Found In
+  5. Sort by full-book count descending
+  6. Write the complete index to: notes/analysis/book{BOOK}-phrase-index-ch{XX}-{YY}.md
+
+  **Important:**
+  - Use Grep for counting — do NOT try to load all chapters into context
+  - Include both the target-range count and the full-book count
+  - Skip extremely common phrases ("he said", "I was", "it was") — focus on distinctive repeated expressions
+  - Include a header noting the date, book number, and chapter range analyzed
+
+  Do NOT use the Agent tool. Do all work directly. Write only research output, no code.
+```
+
+### Agent 1B — Phrase Analyst
+
+After Agent 1A completes, dispatch:
+
+```
+prompt: |
+  You are a literary editor analyzing a fantasy manuscript for phrase repetition patterns.
+
+  **Read these files:**
+  - Target chapters: {list each chapters/book{BOOK}/ch{NN}-final.md in the range XX to YY}
+  - Phrase index: notes/analysis/book{BOOK}-phrase-index-ch{XX}-{YY}.md (from prior analysis)
+  - Voice guidelines: CLAUDE.md (sections 5 and 11 — Phelan's voice and style guide)
+
+  **Task:**
+  1. Read the target chapters with a literary editor's eye
+  2. Using the phrase index as a starting point, analyze:
+     - **Structural repetition**: Repeated sentence structures, paragraph openings, or narrative beats (not just repeated words)
+     - **Crutch phrases**: Transitions, beats, or narration patterns that appear to be authorial habit rather than character voice
+     - **Overused transitions**: Words/phrases used to connect scenes or ideas that have become repetitive
+  3. Distinguish between:
+     - **Intentional voice patterns**: Phelan's established mannerisms per CLAUDE.md (dry observations, ADD tangents, precise cataloguing) — these are FEATURES, not bugs
+     - **Authorial habits**: Repetition that doesn't serve the voice or narrative
+     - **Intentional callbacks**: Phrases repeated deliberately for thematic or narrative effect
+  4. For each finding, provide: the phrase/pattern, example quotes with chapter references, frequency assessment, and whether it's voice vs. habit
+  5. Write the complete analysis to: notes/analysis/book{BOOK}-phrase-analysis-ch{XX}-{YY}.md
+
+  **Format the output as:**
+  - Header with date, book, chapter range
+  - Section 1: Crutch Phrases & Overused Expressions (highest priority)
+  - Section 2: Structural Repetition Patterns
+  - Section 3: Overused Transitions
+  - Section 4: Intentional Voice Patterns (noted but not flagged as problems)
+  - Section 5: Effective Callbacks & Deliberate Repetition
+
+  Do NOT use the Agent tool. Do all work directly. Write only research output, no code.
+```
+
+---
+
+## Phase 2: Continuity Check
+
+Determine agent count: if `(YY - XX + 1) > 7`, split into two agents (2A handles first half of range, 2B handles second half). Otherwise, use one agent.
+
+### Agent 2A — Continuity Checker
+
+Dispatch via Agent tool with `subagent_type: "general-purpose"`:
+
+```
+prompt: |
+  You are a continuity editor for a fantasy manuscript. Your job is to find inconsistencies, timeline errors, and contradictions.
+
+  **Read these files:**
+  - Target chapters: {list each chapters/book{BOOK}/ch{NN}-final.md in the assigned range}
+  - Story summary: world/story-summary-book{BOOK}.md
+  - Timeline: world/timeline-book{BOOK}.md
+  - Exploits log: world/magic/exploits-log.md
+  - Magic rules: world/magic/runic-flow-rules.md
+  - Economy: world/economy.md
+  - All files in characters/ (use Glob to find them, then read relevant ones)
+  - All files in world/locations/ (use Glob to find them, then read relevant ones)
+
+  **Check for:**
+  1. **Timeline consistency**: Do bell references, day-of-week mentions, and elapsed time match the timeline file? Flag any mismatches with specific quotes.
+  2. **Character consistency**: Are names spelled consistently? Do characters know things they shouldn't (or forget things they should know)? Do physical descriptions match character files?
+  3. **World-building facts**: Do currency amounts match economy.md? Do location descriptions match location files? Does magic usage follow runic-flow rules?
+  4. **Plot threads**: Are threads from earlier chapters (per story summary) picked up appropriately? Are there dangling threads that seem forgotten?
+  5. **Internal contradictions**: Do facts within the target range contradict each other? (e.g., a character described as tall in ch3 and short in ch5)
+
+  **For each finding, provide:**
+  - Category (Timeline / Character / World / Plot Thread / Internal)
+  - Severity (Critical = plot hole or major contradiction, Important = notable inconsistency, Minor = nitpick)
+  - The specific text with chapter and approximate location
+  - What it contradicts (with reference to the source file)
+  - Suggested resolution
+
+  **Write the complete report to:** notes/analysis/book{BOOK}-continuity-ch{XX}-{YY}.md
+
+  **Format:**
+  - Header with date, book, chapter range
+  - Summary of findings by severity
+  - Detailed findings grouped by category
+  - Each finding numbered for easy reference
+
+  Do NOT use the Agent tool. Do all work directly. Write only research output, no code.
+```
+
+If the range was split, Agent 2B gets an identical prompt but with its half of the chapter range. After both complete, the orchestrator merges their outputs into a single `book{BOOK}-continuity-ch{XX}-{YY}.md` file.
+
+---
+
+## Phase 3: Story Craft
+
+### Agent 3A — Story Craft Analyst
+
+Dispatch via Agent tool with `subagent_type: "general-purpose"`:
+
+```
+prompt: |
+  You are a developmental editor analyzing a fantasy manuscript for story craft quality.
+
+  **Read these files:**
+  - Target chapters: {list each chapters/book{BOOK}/ch{NN}-final.md in the range XX to YY}
+  - Story summary: world/story-summary-book{BOOK}.md
+  - Book outline: outline/book{BOOK}-outline.md
+  - Master instructions: CLAUDE.md (full file — contains voice guide, style rules, character bible)
+  - Book-specific instructions: chapters/book{BOOK}/CLAUDE.md
+
+  **Analyze the following 8 categories:**
+
+  1. **Premise & Conflict**: Is the central conflict clear and advancing across these chapters? Are stakes escalating appropriately? Does each chapter have its own mini-conflict that serves the larger arc?
+
+  2. **Character Arcs**: Is Phelan's growth visible (even if incremental)? Are supporting cast members serving their narrative functions as defined in CLAUDE.md? Are character motivations clear and consistent?
+
+  3. **Foreshadowing**: Are seeds being planted for future payoffs? Are setups subtle enough to avoid telegraphing? Are earlier setups (from story summary) being paid off in these chapters?
+
+  4. **POV Consistency**: Does every paragraph sound like Phelan? Are there slips into omniscient narration? Does Phelan observe/deduce information rather than magically knowing it?
+
+  5. **Pacing**: How are action/investigation/quiet beats distributed? Are there stretches that drag or rush? Does chapter length vary appropriately with content?
+
+  6. **World-Building Integration**: Is world detail woven into action and observation, or dumped as exposition? Does the world feel lived-in?
+
+  7. **The Noise Convention**: Are parenthetical tangents (*like this*) at the right frequency (4-6 per chapter establishing, 3-5 ongoing)? Are they doing narrative work (revealing character, advancing plot, providing humor) rather than just being decorative?
+
+  8. **What's Working Well**: Specific callouts of strong passages, effective techniques, great character moments, and well-executed craft. Be specific with quotes.
+
+  **For each category, provide:**
+  - Overall assessment for the chapter range
+  - Specific examples with chapter references and quotes
+  - Suggestions where applicable
+
+  **Write the complete analysis to:** notes/analysis/book{BOOK}-storycraft-ch{XX}-{YY}.md
+
+  **Format:**
+  - Header with date, book, chapter range
+  - Executive summary (2-3 sentences)
+  - One section per analysis category (numbered 1-8)
+  - Each section: assessment, examples, suggestions
+
+  Do NOT use the Agent tool. Do all work directly. Write only research output, no code.
+```
+
+---
+
+## Phase 4: Aggregation
+
+The orchestrator (you, the main session) performs this phase directly. Do NOT dispatch a subagent.
+
+1. Read all intermediate reports:
+   - `notes/analysis/book{BOOK}-phrase-index-ch{XX}-{YY}.md`
+   - `notes/analysis/book{BOOK}-phrase-analysis-ch{XX}-{YY}.md`
+   - `notes/analysis/book{BOOK}-continuity-ch{XX}-{YY}.md`
+   - `notes/analysis/book{BOOK}-storycraft-ch{XX}-{YY}.md`
+
+2. Write a consolidated report to `notes/analysis/book{BOOK}-analysis-ch{XX}-{YY}.md` with:
+
+   **Format:**
+   ```
+   # Manuscript Analysis: Book {BOOK}, Chapters {XX}–{YY}
+   **Date:** {today}
+   **Chapters analyzed:** {count}
+   **Analysis phases:** Phrase Analysis, Continuity, Story Craft
+
+   ## Summary
+   - Critical issues: {count}
+   - Important issues: {count}
+   - Suggestions: {count}
+
+   ## Critical Issues
+   {items from all reports rated Critical — plot holes, major continuity breaks, significant voice failures}
+
+   ## Important Issues
+   {items rated Important — repeated phrases needing attention, notable inconsistencies, craft improvements}
+
+   ## Suggestions
+   {lower-priority items — minor repetition, style polish, optional improvements}
+
+   ## What's Working Well
+   {positive findings from story craft report}
+
+   ## Detailed Reports
+   See individual analysis files for full details:
+   - Phrase index: book{BOOK}-phrase-index-ch{XX}-{YY}.md
+   - Phrase analysis: book{BOOK}-phrase-analysis-ch{XX}-{YY}.md
+   - Continuity: book{BOOK}-continuity-ch{XX}-{YY}.md
+   - Story craft: book{BOOK}-storycraft-ch{XX}-{YY}.md
+   ```
+
+3. Deduplicate: if multiple agents flagged the same issue, consolidate into one entry and note which analyses found it.
+
+4. Present a brief summary to the user with the consolidated report path and top findings.
--- a/python-cleanup/SKILL.md
+++ b/python-cleanup/SKILL.md
@@ -0,0 +1,76 @@
+# Python Cleanup Skill
+
+Clean up Python code by formatting, fixing lint issues, removing unused imports, and identifying dead code.
+
+## Usage
+
+Invoke with `/python-cleanup` followed by an optional path or scope:
+
+- `/python-cleanup` - Clean up changed files (git diff)
+- `/python-cleanup src/` - Clean up a specific directory
+- `/python-cleanup src/main.py` - Clean up a specific file
+
+## Workflow
+
+### Step 1: Identify Target Files
+
+If no path specified, find Python files with uncommitted changes:
+```bash
+git diff --name-only --diff-filter=ACMR HEAD | grep '\.py$'
+```
+
+If a path is specified, use that path directly.
+
+### Step 2: Format Code
+
+Run ruff formatter to fix code style:
+```bash
+ruff format <target>
+```
+
+### Step 3: Fix Lint Issues
+
+Auto-fix all fixable lint issues including unused imports:
+```bash
+ruff check --fix --unsafe-fixes <target>
+```
+
+Key rules this fixes:
+- `F401` - Unused imports (removes them)
+- `F841` - Unused variables
+- `I001` - Import sorting
+- `UP` - Python upgrade suggestions
+- `B` - Bugbear issues
+
+### Step 4: Report Remaining Issues
+
+Show any issues that couldn't be auto-fixed:
+```bash
+ruff check <target>
+```
+
+### Step 5: Identify Dead Code (Optional)
+
+Use vulture to find potentially unused code:
+```bash
+vulture <target> --min-confidence 80
+```
+
+If vulture is not installed, skip this step and note it in the summary.
+
+### Step 6: Summary
+
+Provide a summary of:
+- Files processed
+- Issues auto-fixed (count by category)
+- Remaining issues that need manual review
+- Potential dead code identified (if vulture available)
+
+## Configuration
+
+This skill respects project-level `pyproject.toml` or `ruff.toml` configuration if present.
+
+## Dependencies
+
+- `ruff` (required) - Install with `uv add ruff` or `pip install ruff`
+- `vulture` (optional) - Install with `uv add vulture` or `pip install vulture`