# Book Revise

> Critique and improve existing prose through separate editorial gates — structural, emotional, pacing, continuity, audio and read-aloud, line, and copy/proof — and create branch alternatives for pivotal scenes. Ties reader feedback to the exact version seen. Never overwrites previous prose; every substantive pass creates a recoverable version.

- Skill: `nibzard/book-revise` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nibzard/book-revise`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nibzard/book-revise/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nibzard (https://skillmd.com/u/nibzard)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nibzard/book-revise

---


# Book Revise

Improve existing prose without destroying history. “Make it better” is not one operation; run distinct gates separately, and record each pass. No revision overwrites previous prose — every substantive change is a new `text_version`.

This skill inherits every rule in `AGENTS.md`. It never overrides human creative authority or database safety. Route through `$book-guide` first for mixed requests.

## Separate gates

Run passes independently and record each as an `entry`. A pass that changes prose creates **one new text version per materially changed unit**, not one per tiny edit.

1. **Structural** — causality, anchors, payoff, book-level completeness.
2. **Emotional** — choices reveal character; consequences persist; relationships change.
3. **Pacing** — scenes begin late, end early, and earn their length.
4. **Continuity** — facts, timeline, possessions, injuries, knowledge, rules, geography, and promises agree.
5. **Audio** — speakers stay distinguishable; sentences work linearly; exposition is intelligible without visual rereading; repeated formats do not become tedious.
6. **Line** — clarity, rhythm, specificity, unnecessary repetition.
7. **Copy/proof** — grammar, spelling, style-sheet consistency.

State which gate a request maps to before editing. Continuity and audio findings that do not require prose changes are recorded as entries, not versions.

## Branch drafting for pivotal scenes

For a pivotal unit, create several `candidate` versions sharing the same node and `purpose`, different version numbers, `is_current=0`, each testing a different outcome:

- success with an unexpected cost;
- failure that yields useful information;
- another character controlling the scene;
- the apparent antagonist being locally correct;
- the safe choice causing the worst long-term result.

Record what each branch tests in the version `note` or an entry. Only the human switches `is_current`.

## Reader feedback

Store feedback as entries tied to the exact `text_version_id` the reader saw:

```json
{"reader_id": "beta-03", "signal": "attention_drop", "severity": 2, "location": "middle third", "observation_not_solution": true}
```

Separate **observation** (where attention weakened, confusion arose, an expectation formed, emotion intensified) from the reader’s **proposed solution** (one possible response, not a command). Look for repeated signals across readers before recommending changes. Audience participation may create pressure or options; it must not replace the protagonist’s moral agency or the author’s control of the emotional arc.

## Persistence

- a prose-changing pass → new `manuscript` version (safe-transaction pattern) plus a `revision_memo` or `entry` describing the gate and the change;
- branch candidates → new `candidate` versions;
- feedback → version-linked `entry` rows;
- supersedes a planned fact from an old version → retire the old statement (`superseded`) and insert the replacement, preserving the `source_text_version_id` trail.

## Definition of done

A revision turn is complete when the requested gate was run and recorded, prose changes exist as recoverable versions (never overwrites), feedback was tied to the version seen, and the author knows which versions changed and why — without any unauthorized approval or retcon.