revision-continuity

Files (2)

• SKILL.md
• pass-checklists.md · references/

SKILL.md (first lines)

# Revision Continuity

## Overview

Revise existing Story Skills projects without losing continuity. Use this skill for targeted chapter edits, continuity audits, developmental revision, line edits, and pre-flight checks before drafting the next chapter.

## Prerequisites

A story project must already exist. Verify by checking for `story.md` in the project root, then run or inspect `story report .` when CLI access is available. Read `story.md` `language` (a missing field means `en`) and write every revision in that language; when a `story prose` or `story voices` check is reported as skipped for the language, do that check by reading.

## Named Revision Passes

Track a full revision as a ladder of named passes in `story.md`
`revision-passes`, so the work happens in order (big structural changes
before polishing sentences that may be cut) and survives between sessions:

```shell
story passes . --init            # writes the default ladder, keeping existing entries
story passes .                   # checklist with the checks each pass runs
story passes . --start pacing    # mark a pass in-progress
story passes . --done pacing     # mark it done
story next .                     # with story status revising, recommends the next unfinished pass
```

The default ladder is `structure`, `character`, `theme`, `continuity`,
`pacing`, `line`, `copyedit`, `proof`. Each entry is `{pass, status}` with
status `pending`, `in-progress`, or `done`; add a custom kebab-case pass
(`fact-check`, `length`, `sensitivity`) with `story passes . --start <name>`, which
appends it as `in-progress`. The checks per pass, as `story passes .`
prints them, and the checklists in `references/pass-checklists.md` that
each pass works through:

| Pass | Checks | Checklists |
|------|--------|----------------|
| `structure` | `story timeline .`, `story pacing .`, `story diagram arcs` | Reverse outline, pacing waveform, removability audit |
| `character` | `story voices .`, `story knowledge <id> --at <chapter>`, `story diagram relationships` | Developmental revision (motivation, arcs) |
| `theme` | `story report .` | Theme audit |
| `continuity` | `story continuity .`, `story clues .`, `story links .` | Continuity audit, reveal economy, fact check |
| `pacing` | `story pacing .` | Pacing waveform |
| `line` | `story prose .`, `story voices .` | Line edit (the `line-editing` skill) |
| `copyedit` | `story prose .` + `style-sheet.md` | Copyedit (the `line-editing` skill) |
| `proof` | `story build --format print`, `story build --format html` | Proof (the `line-editing` skill) |

Mark a pass `--start` when beginning it and `--done` only when its checks
are clean or every remaining finding is a recorded decision. Set story
`status: revising` so `story next .` points at the next pass.

## Revision Workflow

1. Clarify the pass type unless the user already specified it. Each pass has a checklist in `references/pass-checklists.md` (what to run, read, check, and update); follow it from step 3 on, after the snapshot, because some checks write files:
   - **Continuity audit** - contradictions, stale references, timeline problems, missing backlinks, word-count drift
   - **Developmental revision** - structure, scene purpose, character motivation, pacing, stakes, arc progression
   - **Reverse outline** - what each chapter actually does, diffed against what the plot files say it should do
   - **Theme audit** - whether the ending engages the opening's value-question and early motifs pay off
   - **Pacing waveform** - tension per chapter and dead zones (`story pacing .`)
   - **Reveal economy** - every reveal earned by planted setup and spaced out (`story clues .`)
   - **Removability audit (darling-killing)** - scenes whose removal would change nothing downstream
   - **Length pass** - cut or expand to a target word count from a per-chapter and per-arc budget (`story progress .`, `story pacing .`; a custom `length` pass)
   - **Voice differentiation** - each speaker sounds like themselves (`story voices .`)
   - **Line edit** - clarity, voice, rhythm, dialogue, and sensory detail without changing plot facts (the `line-editing` skill)
   - **Copyedit** - style baseline and surface-detail consistency, not prose quality (the `line-editing` skill)
   - **Fact check** - real-world details against `research/` notes (the `research` skill)
   - **Proof/polish** - small wording, grammar, and formatting fixes on a built copy (the `line-editing` skill)
2. Snapshot the draft before any multi-chapter pass (see Draft Snapshots below), so the pass can be compared and undone.
3. Read the relevant context:
   - `story.md`
   - `chapters/_index.md`
   - The target chapter(s)
   - Previous and next chapters when present
   - Relevant character, location, system, and arc files referenced by the chapter frontmatter
   - Matching scene files in `scenes/`
   - `continuity/state.md`, open questions, and promises/payoffs
   - `plot/timeline.md` and active arc files for continuity-sensitive edits
   - The files the pass checklist lists, and the output of the checks it runs
4. Create a concise revision plan:
   - What will change
   - What must stay fixed for continuity
   - Which files may need updates beyond the chapter
   - Each scene, subplot, or passage the plan cuts, folds into another, or moves, named one by one

   Show the plan to the user and wait for their approval before editing. Cut, fold, or move only what they approve: a removability audit or a length pass proposes cuts, it does not make them. A single targeted edit the user has already spelled out ("revise chapter 3 so Nell hides the log") is its own approval, so state the plan in a line and go on.
5. Make targeted edits directly in markdown files, following the approved plan. Do not create project-local scripts to rewrite prose.
6. Update dependent metadata:
   - Chapter frontmatter `status` (`draft` -> `revised`, `revised` -> `final` only when appropriate)
   - Chapter `word-count` via CLI when available
   - `plot/timeline.md` if planned events or backstory changed (scene `date` and `time` say when drafted scenes happen)
   - `scenes/` records if POV, location, participants, or state changes moved
   - `continuity/state.md` when knowledge or object ownership changed
   - The one record that owns each setup the revision moves, adds, or cuts: a promise, clue, or question file (`status` and its chapter fields), or, for a small hint with no record, its arc `## Foreshadowing` row. Never record one setup in two places
   - Arc plot points if the revision changes which chapter hits them
   - Character or location files when state, relationship, or location references changed
7. Run maintenance:

```shell
story reindex .
story wordcount . --write
story check .
story doctor .
```

For structural or reveal passes, also run `story pacing .` and `story clues .`; after dialogue changes, `story voices .`. When working through named passes, finish with `story passes . --done <pass>`.

If `story.md` links other books through `follows` or `precedes`, also run `story series .` so the revision does not break canon shared with sequels or prequels. See the `series-continuity` skill.

`story continuity` deterministically checks death ordering (`died-in` vs later appearances, characters `deceased` with no `died-in` listed in any cast, and a character `status` progression to `deceased` followed by later appearances or learning, resolved in story order), status progressions that contradict `died-in` or `revived-in`, promise/question chapter ordering, unfired setups, POV/cast consistency, and `continuity/state.md` references. For intentional flashbacks, memories, or recordings of dead characters, list them under chapter or scene `mentions` instead of `characters`. A dead POV narrator keeps `pov` and is also listed in `mentions`; a resurrected character gets `revived-in: chapter-NN`; a death in an outline chapter is planned, not in force, so the character may keep `status: alive` and a later chapter may still list them until that chapter is drafted. Chapters dated on both sides compare deaths and `story knowledge` by story date, and a dual-timeline book's chapters take a `strand` so each timeline keeps its own clock and its own route check. `story knowledge` and `story context` mark a fact the character knows from a chapter the reader has not reached as `character-knowledge` with `do not reveal`: treat it as known, and do not state it. It also warns when `continuity/state.md` drifts from scene `state-changes` knowledge and artifact owners, from deaths, or from casts.

When any chapter has `choices`, the book branches and `story continuity` reads deaths, revivals, knowledge, and progressions along the paths of choices, while the promise, question, and clue ledgers and the clock still read chapter numbers. Revise it with the `interactive-fiction` skill as well: it covers `state-differs-by-path`, `unreachable-chapter`, rejoin prose, endings, and the hand checks for each path.

If `story` is not installed, use the bundled fallback `node ../story-maintenance/scripts/story.js` with the same arguments. Use `node <checkout>/bin/story.js` instead only when the user names a Story Skills repository checkout or you are working in one. Write the script as an absolute path (resolve the fallback relative to this skill folder) and run it from the folder you would run `story` from, so `.` and other relative paths keep their meaning. Use Node, not Bun or a package script: Bun would load that folder's `bunfig.toml` (which can run code) and `.env`, and a package script runs from the checkout's root.

## Draft Snapshots

Take a snapshot before a revision pass that touches more than one chapter, and name it after the draft it preserves (`draft-1`, `pre-beta-edit`).

- **Git projects:** work from the book's folder, the one that holds `story.md` (`cd` there first), because `-- .` below means the current folder. Make sure `.gitignore` lists `dist/` (`story init` writes one that does, but older or hand-made projects may lack it) so build output such as EPUB and DOCX files stays out of every snapshot and `story compare --ref` baseline; add the line if it is missing. Then run `git status --untracked-files=all -- .` and show the user what it lists. Look through it for private files (a `.env`, keys or credentials, scanned documents): unless the user says to commit one, add it to `.gitignore` first. Ask the user before committing anything; with approval, commit the book's folder only and tag it: `git add -A -- . && git commit -m "Draft 1 before developmental pass" -- . && git tag draft-1`. The `-- .` keeps files outside the book's folder out of the add and the commit, staged or not; when the book's folder is the repository root, that is the whole repository. If the status lists nothing, skip the add and the commit and run only the tag. If the user declines the commit, or it fails, never tag the last commit over an uncommitted tree: take a `story snapshot` as below instead, or stop. Never push, rewrite history, or delete tags without explicit approval.
- **Projects without git:** offer to run `git init` first. If the user declines, take a named snapshot: `story snapshot draft-1 --path .` copies the project's markdown to `.snapshots/draft-1/`, which every `story` command skips. It refuses a name already taken; ask before replacing one with `--force`. `story snapshot --list --path .` shows the snapshots there are. Never copy the project into a folder of its own by hand, where `story` commands would scan the copy.

After the pass, compare with the snapshot and report the result:

From danjdewhurst/story-skills, MIT.

More from danjdewhurst/story-skills