/story-maintenance

name: story-maintenance
description: This skill should be used when the user asks to "validate", "reindex", "repair registries", "check links", "run the continuity, pacing, clue, voice, or name checks", "count words", "summarize a story project", "import an existing manuscript", "export a manuscript", "run a build", "generate a diagram", "record revision-pass status with `story passes`", "run the story CLI", or wants deterministic maintenance on a Story Skills markdown project. It runs the CLI and reads its output; NOT for judging a finding or revising the story to fix it (use revision-continuity for continuity errors and revision passes, plot-structure for pacing, voice-style for voices and prose, genre-craft for clues and fair play), or for sharing a review copy with readers (use feedback-triage).

Story Maintenance

Overview

Run deterministic maintenance for Story Skills projects. Use the CLI for structure validation, registry rebuilds, word counts, link checks, continuity checks, project reports, next-action reports, pacing, clue, voice, and name checks, revision-pass tracking, Mermaid diagrams, schema migration, entity helpers, manuscript import, and manuscript export and builds. The creative skills still own story decisions; this skill handles mechanical consistency. It runs a check and reports what it found, and fixes mechanical problems such as broken references and stale registries; deciding what a finding means for the story, and revising the story to fix it, belongs to revision-continuity, plot-structure, voice-style, or genre-craft.

CLI Access

Prefer the first available command:

1. `story <command>` - when the package bin is installed 2. `node scripts/story.js <command>` - bundled fallback, resolving `scripts/story.js` relative to this skill folder 3. `node <checkout>/bin/story.js <command>` - only when the user names a Story Skills repository checkout or you are working in one, where `<checkout>` is its path

Write the script in forms 2 and 3 as an absolute path and run the command from the folder you would run `story` from, so `.` and other relative paths keep their meaning. Use Node, not Bun or the `story` script in the checkout's `package.json`: Bun would load that folder's `bunfig.toml` (which can run code) and `.env`, and a package script runs from the checkout's root, so `.` would be the checkout, not the story project.

If none of these are available, perform the requested maintenance manually using the shared conventions in `references/conventions.md`.

Run the installed or bundled CLI in place. Do not copy `scripts/story.js` into the user's story project, and do not create project-local build scripts, generator scripts, or bulk writer scripts to generate story content. Story projects should remain markdown-first, plus explicitly requested exports such as `dist/manuscript.md`.

Commands

Run commands from the story project root, or pass the story path explicitly.

After any change to story files, run the maintenance block, in this order:

story reindex .
story wordcount . --write
story check .

`reindex` rebuilds the registries, `wordcount --write` updates chapter counts (and reindexes again), and `check` then runs `validate`, `links`, and `continuity` over the settled files. `check` exits 1 only on errors; warnings print but do not fail it (`--strict` makes them fail). Every skill ends its edits with this block, followed by any skill-specific checks such as `story clues .` or `story pacing .`.

For the full command set, run `story --help` (every command) or `story <command> --help` (its flags), or read `references/commands.md`, which gives an example of each.

The check commands' detailed rules live in `references/continuity-checks.md`, one section per command. Read the matching section before explaining or acting on a finding. The editing commands' detail (`add`, `rename`, `move`, `remove`, `split`, `merge`, `import`) lives in `references/editing-commands.md`, and each build format's in `references/builds.md`.

Use:

• `check` at the end of an editing session, after `reindex` and `wordcount --write`, and before reporting the project clean: it runs `validate`, `links`, and `continuity` over one scan, lists each finding once, and exits 1 if any of them has an error (`--strict` also fails on warnings). Run the three separately when you want one check's findings
• `validate` after initialization and at the end of any multi-file edit
• `reindex` after adding, removing, renaming, or moving any entity file. It rebuilds the character, location, system, faction, artifact, arc, chapter, scene, question, promise, clue, and glossary registries. `story add` reindexes itself; a hand-written file does not
• `wordcount --write` after writing or revising chapters
• `links` after changing character relationships, notable locations, arc participants, or chapter references
• `continuity` after drafting or revising a chapter, and whenever the user asks about contradictions, dead characters appearing, unfired setups, or stale state. It checks deaths and revivals, promise, question, and clue ordering, Chekhov gaps, casts and `status: cut` characters, `continuity/state.md`, prop custody, and clock and route plausibility; intentional exceptions go in `continuity/exemptions.md`. In a book whose chapters carry `choices`, read Branching books there too. Rules: `references/continuity-checks.md` (continuity).
• `compare` after a revision pass, or when the user asks what changed since a draft: it needs exactly one of `--ref` (a git ref), `--against` (another copy of the project), or `--snapshot` (a snapshot saved with `story snapshot <name>`, for a project without git; `--list` shows them), and `--anchor <label>` maps review-copy paragraph labels to the current text. Rules: `references/continuity-checks.md` (compare).
• `notes <file.docx>` when an editor or reader returns a Word build of the book with comments or tracked changes: it lists each comment, reply,