novel-story-telling

name

novel-story-telling

description

Design and control whole-novel storytelling, reader mental-model progression, chapter-to-chapter flow, conflict escalation and resolution, reveals, foreshadowing, continuity, safe chapter-file creation, and next-chapter handoffs for this Markdown novel repository. Use when planning, drafting, or revising story structure, modeling what a target reader knows, infers, misreads, or still asks at each story turn, auditing cohesion or reader orientation, preparing or writing the next chapter from prior context, creating a template-conformant chapter under chapters/, checking contradictions, maintaining story-state summaries, selecting genre-specific narrative devices, or auditing character, timeline, world-rule, clue, MacGuffin, and plot-thread continuity.

Novel Story Telling

Before running a bundled command, resolve <skill-dir> to the absolute directory containing this SKILL.md. Keep --project-root pointed at the active novel workspace, not at the skill or plugin installation.

Operating Contract

Treat chapters/ as manuscript canon and all other source directories as planning and continuity evidence. Follow AGENTS.md. Never edit published/ as source.

Write all agent instructions, temporary prompts, schemas, and script inputs in English. Write manuscript prose and author-facing creative output in this order of precedence:

1. the language explicitly requested by the author;
2. project.md language;
3. style/000.style-guide.md language;
4. the dominant language of recent chapters.

Preserve names, honorifics, invented terms, and spelling from canonical files. Do not translate them unless requested.

Resolve conflicts by authority: explicit author direction > final source > revision source > latest manuscript fact > draft source > outline or seed. Report unresolved conflicts; do not silently choose or invent canon.

Core Workflow

1. Orient

Read AGENTS.md, project.md, style/000.style-guide.md, plot/000.master-plot.md, and outlines/000.master-outline.md. Determine:

• output language and prose constraints;
• current story promise and governing question;
• target reader baseline, including genre literacy, prior reader-visible anchors, active questions, and unfamiliar terminology;
• target chapter and its irreversible change;
• active plot threads, promises, clues, and MacGuffins;
• current character knowledge, desire, condition, relationship, and location;
• hard world rules and timeline constraints.

Do not load every source file into context by default.

2. Build A Bounded Context Pack

Run:

python3 "<skill-dir>/scripts/build_story_context.py" \
  --project-root . \
  --chapter <number> \
  --query "<POV, location, entities, conflict, or theme>" \
  --max-tokens 6000 \
  --output-language auto \
  --output /tmp/story-context.md

Read the resulting pack. It prioritizes explicit links, active master sources, the target outline, recent chapters, the story ledger, and query matches. It includes source paths so every inferred constraint can be checked against canon.

Treat the context pack as author-side evidence, not proof that a reader has seen a fact. Reconstruct reader knowledge only from prior publishable ## Draft text and explicitly recorded reader-facing evidence. Synopsis, Revision Notes, outlines, character sheets, hidden truth, and canon-fact ledger entries do not count as reader exposure. Treat recorded expected inferences as editorial hypotheses and spot-check them against Draft before relying on them.

Increase the budget only when the pack proves insufficient. Prefer linked fact cards and Continuity sections over full old chapters. Read a full source file only to resolve ambiguity or recover scene-level nuance.

3. Select Narrative Structure

Read story-flow.md for whole-book and chapter-unit control. Read only the genre references needed for the current project:

• wuxia.md for jianghu ethics, obligations, factions, techniques, and reputation;
• science-fiction.md for speculative premises, system consequences, and rule-bound solutions;
• time-travel-and-loop.md for temporal ontologies, causal state, and repeated-loop progression;
• mystery.md for fair clues, truth timelines, suspect logic, and reveal control;
• drama.md for relationship pressure, recognition, reversal, and costly repair;
• romantic-entanglement.md for jealousy, triangle dynamics, intimacy allocation, betrayal, and relational aftermath.

For hybrids, select one primary story engine and at most two secondary engines per chapter. Preserve each genre's reader contract. For example, a romantic subplot may intensify a mystery, but it must not excuse an unseeded solution.

4. Establish The Story-Control Frame

Before outlining or drafting, state compactly:

• Promise: the experience and central question owed to the reader.
• Pressure source: the person, system, relationship, scarcity, secret, or clock preventing an easy answer.
• Change chain: cause → decision → consequence → new constraint.
• Thread states: dormant, active, escalating, converging, paid, or intentionally deferred.
• Information states: what the reader, viewpoint character, allies, and opponents know or falsely believe.
• Reader-model path: entry model → recalled anchor → reader-visible cue → intended inference → confirmation, contradiction, or reframe → exit question or prediction.
• Cost ladder: what becomes harder, more public, more intimate, less reversible, or more morally expensive.
• Resolution condition: the decision and established mechanism capable of answering the promise.

Keep a distinction between facts, plans, and hypotheses. A plan in an outline is not yet an event in canon.

5. Design The Next-Chapter Contract

Give the chapter one primary job. Define:

• entry state and inherited emotional residue;
• viewpoint, location, world time, and elapsed time;
• immediate objective and opposition;
• active thread or promise being moved;
• reader entry model: what the target reader can recall, currently believes or suspects, and wants answered;
• information to expose, reinterpret, conceal legitimately, or pay off;
• reader update: the primary observation and inference the chapter enables, the textual prerequisite for it, and any ambiguity intentionally retained;
• one meaningful relationship or power shift;
• one irreversible or costly change;
• reader exit model: what picture has become clearer or been reframed, and what question or prediction now pulls the reader forward;
• exit state and hook into the following chapter;
• details that must not change.

Use the chapter motion inherit → pressure → choice → consequence → handoff. Vary scene rhythm and emotional temperature inside that motion. Do not force a twist when a decision, recognition, or cost produces the stronger turn.

6. Run Pre-Draft Continuity Gates

Run the structural audit:

python3 "<skill-dir>/scripts/check_continuity.py" --project-root .

Then perform the semantic gate using the context pack:

Dimension	Entry fact	Proposed change	Evidence	Valid transition?
Character knowledge
Physical state and possessions
Relationship and obligation
Location and elapsed time
World or genre rule
Clue, secret, or reveal
MacGuffin custody and meaning
Open thread and promised payoff

Fix an invalid transition in the plan before drafting. If the author intends a retcon, identify every affected source file and obtain confirmation before changing established canon.

Then map the chapter's major beats with the reader-model table in story-flow.md. Every required inference must have reader-visible prerequisites. Preserve local orientation—who wants what, what changed, and why it matters—even when the larger truth remains hidden. Split or sequence a beat that requires several unrelated new names, rules, timelines, and causal claims at once unless overload is an intentional experience.

7. Draft Or Revise The Chapter

Follow the author-approved chapter contract and existing voice. Make every scene change at least one of: knowledge, leverage, relationship, objective, risk, resource, location, or commitment.

Preserve causal links. Use therefore or but transitions between major beats more often than unrelated and then transitions. Let relief expose consequences, deepen attachment, or reposition the next threat.

Compose information as a reader-state transition: anchor the current picture, present a perceivable cue, permit the intended inference, and let action or consequence use that update. The reader need not know the hidden truth, but must be able to understand the immediate situation and recover the intended causal bridge. Prefer reordering, dramatizing, bridging, or pruning information over repairing every gap with explanation. Preserve rewarding subtext and inference instead of explaining away all ambiguity.

Do not hide information that the viewpoint character is actively thinking merely to manufacture surprise. Hide significance, access, motive, or interpretation instead.

For a new chapter, prepare a reviewed UTF-8 JSON payload. Use English field names and write title, synopsis, draft, and creative notes in the manuscript language:

{
  "number": 7,
  "title": "The Burned Index",
  "slug": "the-burned-index",
  "status": "draft",
  "pov": "char-protagonist",
  "timeline": "Day 12, after sunset",
  "setting": "world-royal-archive",
  "word_target": 2500,
  "characters": ["char-protagonist"],
  "materials": [],
  "macguffins": ["macguffin-burned-index"],
  "plot_threads": ["plot-main"],
  "outline": "outline-chapter-007",
  "published": false,
  "tags": [],
  "synopsis": "One or two paragraphs describing the chapter's change.",
  "draft": "Complete manuscript prose.",
  "revision_notes": "Optional reviewed notes."
}

Write it with the bundled guardrail:

python3 "<skill-dir>/scripts/write_chapter.py" \
  --project-root . \
  --input /tmp/chapter-007.json

The script must create exactly chapters/NNN.lowercase-ascii-slug.md, populate the repository chapter schema, and refuse any existing chapter number or path. Never bypass that refusal. If the number already exists, treat the task as a revision and edit that file minimally; do not regenerate or replace the whole file. Preserve its created date, set updated to the current ISO date, keep number, id, title, slug, filename, and H1 synchronized, and retain author text outside the requested revision.

Every chapter file must follow chapters/_template.md and contain exactly one H1 matching title, followed by exactly one each of ## Synopsis, ## Draft, and ## Revision Notes. Put manuscript prose only in ## Draft. Remove all template placeholder prose. Do not write a chapter outside chapters/, nest it in a subdirectory, omit YAML arrays, or invent non-ASCII filenames.

Treat the chapter file as an editorial container: only ## Draft is publishable. Keep Synopsis and Revision Notes useful to writers, but never repeat their text as a preface, summary, or appendix inside Draft.

Use the Draft Markdown contract consistently:

• Use normal Markdown paragraph boundaries: only a blank line starts a new paragraph. Dialogue markup does not force a paragraph boundary.
• Keep narration as plain prose. Wrap every spoken range as exact *“…”*, whether it stands alone or shares a paragraph with narration, as in *“Approved.”* Rhea said. EPUB maps only that range to <i class="dialog"> with serif italic styling.
• Do not allow 5 consecutive dialogue-only paragraphs. Before the fifth, add a speaker anchor, meaningful action, narration beat, or indirect response. Do not add an empty attribution merely to satisfy the gate; use a beat that also clarifies speaker, emotion, power, space, or changed information.
• Reserve unquoted *…* for interior thought. Use curly single quotes ‘…’ for cited wording, remembered phrasing, or a quotation nested inside speech. A curly double-quoted span anywhere outside exact *“…”* markers is an error because it cannot be styled or classified safely.
• Use **…** only for genuine strong emphasis. Keep every marker pair balanced on one line.
• Use inline backticks only for literal machine output, UI labels, filenames, code identifiers, or log text.
• Put --- alone between blank lines for a scene or time break. Never use * * * or a decorative bullet sequence.
• Do not use lists, blockquotes, or fenced code blocks anywhere inside Draft. Reserve H3 through H6 for genuine subheadings and do not add another H2 inside Draft.

Immediately after creating or revising the file, run:

python3 "<skill-dir>/scripts/check_continuity.py" \
  --project-root . \
  --strict

Resolve every error. Review warnings and either fix them or report why they are intentional. Do not present a malformed chapter as completed.

After the structural gate, run the reader mental-model audit in story-flow.md using only reader-visible Draft text. At each scene or major turn, state what the target reader can now describe, likely believes or suspects, still asks, and anticipates. Compare that reconstruction with the intended trajectory and repair accidental confusion, author-knowledge leakage, unsupported inference, cognitive overload, or inert repetition.

The strict gate must reject curly double-quoted speech without the surrounding emphasis, straight ASCII dialogue quotes, and 5 consecutive dialogue-only paragraphs without a readability break. It must accept narration before or after a marked dialogue range in the same paragraph, shorter dialogue-only runs, unquoted italic interior thought, and curly single-quoted cited wording.

8. Post-Draft State Update

After the author accepts or finalizes a chapter:

1. Update source files for newly canonical character, world, plot, MacGuffin, or style facts.
2. Prepare a reviewed JSON fact card in the manuscript language:

{
  "chapter": 12,
  "title": "Chapter title",
  "summary": "Objective account of what changed.",
  "canon_facts": [],
  "state_changes": [],
  "timeline_changes": [],
  "knowledge_changes": [],
  "reader_model_changes": [
    {
      "id": "reader-model-change-id",
      "status": "expected",
      "evidence": "Reader-visible detail in Draft.",
      "expected_inference": "What the target reader can now infer.",
      "uncertainty": "Alternative interpretation or confidence limit."
    }
  ],
  "open_reader_questions": [],
  "macguffin_changes": [],
  "open_threads": [],
  "resolved_threads": [],
  "uncertainties": []
}

Keep reader_model_changes editorial rather than canonical. Use separate evidence and expected_inference fields, and record an uncertainty whenever another interpretation remains plausible. Record open_reader_questions only when the chapter intentionally keeps them alive; do not use this section for missing explanations or continuity gaps.

3. Preview the deterministic ledger change:

python3 "<skill-dir>/scripts/update_story_ledger.py" \
  --project-root . --input /tmp/chapter-state.json --dry-run

4. After verifying every item against the chapter, rerun without --dry-run.
5. Rebuild the next chapter's context pack and rerun the continuity audit.

Never record speculation as a fact. Put ambiguity in uncertainties with competing interpretations.

Token Discipline

• Use the ledger for stable outcomes and recent chapter excerpts for voice and immediate physical continuity.
• Retrieve by explicit source links before lexical relevance.
• Keep hard invariants even when they appear unrelated to the current scene.
• Trim prose before trimming rules, obligations, clue states, or character knowledge.
• Recompute context after an accepted chapter rather than carrying a stale chat summary forward.
• Treat token estimates as conservative approximations; inspect the generated pack size before expanding it.

Completion Gate

Do not finish a story-planning or chapter task until:

• the target change advances the story promise or intentionally complicates it;
• escalation changes kind or cost, not only volume;
• the chapter exit differs materially from its entry;
• the target reader's exit model differs intentionally from its entry model;
• every required reader inference has prior reader-visible evidence or a recoverable causal bridge;
• intended ambiguity preserves local orientation and is not accidental confusion;
• all used knowledge, rules, objects, and relationships have provenance;
• setups and payoffs remain tracked;
• the output language and prose style match the author's contract;
• structural audit errors are resolved;
• the chapter exists directly under chapters/ with synchronized filename, frontmatter, H1, and required body sections;
• Draft prose follows the paragraph, dialogue, emphasis, literal-text, and scene-break Markdown contract;
• new canon is reflected in source files and the reviewed story ledger when applicable.