| name | book-revise |
| description | 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. |
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.
- Structural — causality, anchors, payoff, book-level completeness.
- Emotional — choices reveal character; consequences persist; relationships change.
- Pacing — scenes begin late, end early, and earn their length.
- Continuity — facts, timeline, possessions, injuries, knowledge, rules, geography, and promises agree.
- Audio — speakers stay distinguishable; sentences work linearly; exposition is intelligible without visual rereading; repeated formats do not become tedious.
- Line — clarity, rhythm, specificity, unnecessary repetition.
- 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:
{"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.
