Update to Novelist

{
  "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 273
    },
    {
      "relative_path": "references/drama.md",
      "size_in_bytes": 5988
    },
    {
      "relative_path": "references/mystery.md",
      "size_in_bytes": 7094
    },
    {
      "relative_path": "references/romantic-entanglement.md",
      "size_in_bytes": 7132
    },
    {
      "relative_path": "references/science-fiction.md",
      "size_in_bytes": 7132
    },
    {
      "relative_path": "references/story-flow.md",
      "size_in_bytes": 13315
    },
    {
      "relative_path": "references/time-travel-and-loop.md",
      "size_in_bytes": 7774
    },
    {
      "relative_path": "references/wuxia.md",
      "size_in_bytes": 7825
    },
    {
      "relative_path": "scripts/build_story_context.py",
      "size_in_bytes": 8853
    },
    {
      "relative_path": "scripts/check_continuity.py",
      "size_in_bytes": 18520
    },
    {
      "relative_path": "scripts/story_io.py",
      "size_in_bytes": 7848
    },
    {
      "relative_path": "scripts/update_story_ledger.py",
      "size_in_bytes": 7577
    },
    {
      "relative_path": "scripts/write_chapter.py",
      "size_in_bytes": 7680
    },
    {
      "relative_path": "tests/test_chapter_markup.py",
      "size_in_bytes": 4900
    },
    {
      "relative_path": "tests/test_story_ledger.py",
      "size_in_bytes": 2452
    }
  ],
  "name": "novel-story-telling",
  "skill_md_contents": "---\nname: novel-story-telling\ndescription: 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.\n---\n\n# Novel Story Telling\n\nBefore running a bundled command, resolve `<skill-dir>` to the absolute directory\ncontaining this `SKILL.md`. Keep `--project-root` pointed at the active novel\nworkspace, not at the skill or plugin installation.\n\n## Operating Contract\n\nTreat `chapters/` as manuscript canon and all other source directories as planning and continuity evidence. Follow `AGENTS.md`. Never edit `published/` as source.\n\nWrite all agent instructions, temporary prompts, schemas, and script inputs in English. Write manuscript prose and author-facing creative output in this order of precedence:\n\n1. the language explicitly requested by the author;\n2. `project.md` `language`;\n3. `style/000.style-guide.md` `language`;\n4. the dominant language of recent chapters.\n\nPreserve names, honorifics, invented terms, and spelling from canonical files. Do not translate them unless requested.\n\nResolve 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.\n\n## Analytical Review Routing Boundary\n\nKeep analytical review separate from ordinary planning, drafting, and revision.\nDo not invoke `analytical-review` unless the author explicitly requests\ncritique/review or explicitly delegates the complete autonomous novel lifecycle\nfrom initial planning through publication.\n\nFor that fully autonomous start-to-publication request only, after all chapters\nare drafted and before calling `publish-novel`:\n\n1. run whole-manuscript `analytical-review`;\n2. record each material finding as `apply`, `defer`, or `reject` with a concise\n   rationale;\n3. apply selected findings through this storytelling workflow and update canon;\n4. run one bounded analytical regression review;\n5. complete strict continuity validation;\n6. call `publish-novel` for deterministic packaging.\n\nAn ordinary request to finish remaining chapters, revise known material, or\npublish an existing manuscript does not by itself authorize this loop. If the\nauthor explicitly asks for review and revision together, keep diagnosis and\napplication distinct and preserve finding IDs through the handoff.\n\n## Core Workflow\n\n### 1. Orient\n\nRead `AGENTS.md`, `project.md`, `style/000.style-guide.md`, `plot/000.master-plot.md`, and `outlines/000.master-outline.md`. Determine:\n\n- output language and prose constraints;\n- current story promise and governing question;\n- target reader baseline, including genre literacy, prior reader-visible anchors, active questions, and unfamiliar terminology;\n- target chapter and its irreversible change;\n- active plot threads, promises, clues, and MacGuffins;\n- current character knowledge, desire, condition, relationship, and location;\n- hard world rules and timeline constraints.\n\nDo not load every source file into context by default.\n\n### 2. Build A Bounded Context Pack\n\nRun:\n\n```bash\npython3 \"<skill-dir>/scripts/build_story_context.py\" \\\n  --project-root . \\\n  --chapter <number> \\\n  --query \"<POV, location, entities, conflict, or theme>\" \\\n  --max-tokens 6000 \\\n  --output-language auto \\\n  --output /tmp/story-context.md\n```\n\nRead 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.\n\nTreat 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.\n\nIncrease 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.\n\n### 3. Select Narrative Structure\n\nRead [story-flow.md](references/story-flow.md) for whole-book and chapter-unit control. Read only the genre references needed for the current project:\n\n- [wuxia.md](references/wuxia.md) for jianghu ethics, obligations, factions, techniques, and reputation;\n- [science-fiction.md](references/science-fiction.md) for speculative premises, system consequences, and rule-bound solutions;\n- [time-travel-and-loop.md](references/time-travel-and-loop.md) for temporal ontologies, causal state, and repeated-loop progression;\n- [mystery.md](references/mystery.md) for fair clues, truth timelines, suspect logic, and reveal control;\n- [drama.md](references/drama.md) for relationship pressure, recognition, reversal, and costly repair;\n- [romantic-entanglement.md](references/romantic-entanglement.md) for jealousy, triangle dynamics, intimacy allocation, betrayal, and relational aftermath.\n\nFor 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.\n\n### 4. Establish The Story-Control Frame\n\nBefore outlining or drafting, state compactly:\n\n- **Promise:** the experience and central question owed to the reader.\n- **Pressure source:** the person, system, relationship, scarcity, secret, or clock preventing an easy answer.\n- **Change chain:** cause → decision → consequence → new constraint.\n- **Thread states:** dormant, active, escalating, converging, paid, or intentionally deferred.\n- **Information states:** what the reader, viewpoint character, allies, and opponents know or falsely believe.\n- **Reader-model path:** entry model → recalled anchor → reader-visible cue → intended inference → confirmation, contradiction, or reframe → exit question or prediction.\n- **Cost ladder:** what becomes harder, more public, more intimate, less reversible, or more morally expensive.\n- **Resolution condition:** the decision and established mechanism capable of answering the promise.\n\nKeep a distinction between facts, plans, and hypotheses. A plan in an outline is not yet an event in canon.\n\n### 5. Design The Next-Chapter Contract\n\nGive the chapter one primary job. Define:\n\n- entry state and inherited emotional residue;\n- viewpoint, location, world time, and elapsed time;\n- immediate objective and opposition;\n- active thread or promise being moved;\n- reader entry model: what the target reader can recall, currently believes or suspects, and wants answered;\n- information to expose, reinterpret, conceal legitimately, or pay off;\n- reader update: the primary observation and inference the chapter enables, the textual prerequisite for it, and any ambiguity intentionally retained;\n- one meaningful relationship or power shift;\n- one irreversible or costly change;\n- reader exit model: what picture has become clearer or been reframed, and what question or prediction now pulls the reader forward;\n- exit state and hook into the following chapter;\n- details that must not change.\n\nUse 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.\n\n### 6. Run Pre-Draft Continuity Gates\n\nRun the structural audit:\n\n```bash\npython3 \"<skill-dir>/scripts/check_continuity.py\" --project-root .\n```\n\nThen perform the semantic gate using the context pack:\n\n| Dimension | Entry fact | Proposed change | Evidence | Valid transition? |\n| --- | --- | --- | --- | --- |\n| Character knowledge |  |  |  |  |\n| Physical state and possessions |  |  |  |  |\n| Relationship and obligation |  |  |  |  |\n| Location and elapsed time |  |  |  |  |\n| World or genre rule |  |  |  |  |\n| Clue, secret, or reveal |  |  |  |  |\n| MacGuffin custody and meaning |  |  |  |  |\n| Open thread and promised payoff |  |  |  |  |\n\nFix 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.\n\nThen map the chapter's major beats with the reader-model table in [story-flow.md](references/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.\n\n### 7. Draft Or Revise The Chapter\n\nFollow 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.\n\nPreserve 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.\n\nCompose 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.\n\nDo not hide information that the viewpoint character is actively thinking merely to manufacture surprise. Hide significance, access, motive, or interpretation instead.\n\nFor 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:\n\n```json\n{\n  \"number\": 7,\n  \"title\": \"The Burned Index\",\n  \"slug\": \"the-burned-index\",\n  \"status\": \"draft\",\n  \"pov\": \"char-protagonist\",\n  \"timeline\": \"Day 12, after sunset\",\n  \"setting\": \"world-royal-archive\",\n  \"word_target\": 2500,\n  \"characters\": [\"char-protagonist\"],\n  \"materials\": [],\n  \"macguffins\": [\"macguffin-burned-index\"],\n  \"plot_threads\": [\"plot-main\"],\n  \"outline\": \"outline-chapter-007\",\n  \"published\": false,\n  \"tags\": [],\n  \"synopsis\": \"One or two paragraphs describing the chapter's change.\",\n  \"draft\": \"Complete manuscript prose.\",\n  \"revision_notes\": \"Optional reviewed notes.\"\n}\n```\n\nWrite it with the bundled guardrail:\n\n```bash\npython3 \"<skill-dir>/scripts/write_chapter.py\" \\\n  --project-root . \\\n  --input /tmp/chapter-007.json\n```\n\nThe 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.\n\nEvery 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.\n\nTreat the chapter file as an editorial container: only `## Draft` is\npublishable. Keep Synopsis and Revision Notes useful to writers, but never\nrepeat their text as a preface, summary, or appendix inside Draft.\n\nUse the Draft Markdown contract consistently:\n\n- Use normal Markdown paragraph boundaries: only a blank line starts a new\n  paragraph. Dialogue markup does not force a paragraph boundary.\n- Keep narration as plain prose. Wrap every spoken range as exact `*“…”*`,\n  whether it stands alone or shares a paragraph with narration, as in\n  `*“Approved.”* Rhea said.` EPUB maps only that range to\n  `<i class=\"dialog\">` with serif italic styling.\n- Do not allow 5 consecutive dialogue-only paragraphs. Before the fifth, add a\n  speaker anchor, meaningful action, narration beat, or indirect response. Do\n  not add an empty attribution merely to satisfy the gate; use a beat that also\n  clarifies speaker, emotion, power, space, or changed information.\n- Reserve unquoted `*…*` for interior thought. Use curly single quotes `‘…’`\n  for cited wording, remembered phrasing, or a quotation nested inside speech.\n  A curly double-quoted span anywhere outside exact `*“…”*` markers is an error\n  because it cannot be styled or classified safely.\n- Use `**…**` only for genuine strong emphasis. Keep every marker pair balanced\n  on one line.\n- Use inline backticks only for literal machine output, UI labels, filenames,\n  code identifiers, or log text.\n- Put `---` alone between blank lines for a scene or time break. Never use\n  `* * *` or a decorative bullet sequence.\n- Do not use lists, blockquotes, or fenced code blocks anywhere inside Draft.\n  Reserve H3 through H6 for genuine subheadings and do not add another H2 inside\n  Draft.\n\nImmediately after creating or revising the file, run:\n\n```bash\npython3 \"<skill-dir>/scripts/check_continuity.py\" \\\n  --project-root . \\\n  --strict\n```\n\nResolve every error. Review warnings and either fix them or report why they are intentional. Do not present a malformed chapter as completed.\n\nAfter the structural gate, run the reader mental-model audit in [story-flow.md](references/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.\n\nThe strict gate must reject curly double-quoted speech without the surrounding\nemphasis, straight ASCII dialogue quotes, and 5 consecutive dialogue-only\nparagraphs without a readability break. It must accept narration before or\nafter a marked dialogue range in the same paragraph, shorter dialogue-only\nruns, unquoted italic interior thought, and curly single-quoted cited wording.\n\n### 8. Post-Draft State Update\n\nAfter the author accepts or finalizes a chapter:\n\n1. Update source files for newly canonical character, world, plot, MacGuffin, or style facts.\n2. Prepare a reviewed JSON fact card in the manuscript language:\n\n```json\n{\n  \"chapter\": 12,\n  \"title\": \"Chapter title\",\n  \"summary\": \"Objective account of what changed.\",\n  \"canon_facts\": [],\n  \"state_changes\": [],\n  \"timeline_changes\": [],\n  \"knowledge_changes\": [],\n  \"reader_model_changes\": [\n    {\n      \"id\": \"reader-model-change-id\",\n      \"status\": \"expected\",\n      \"evidence\": \"Reader-visible detail in Draft.\",\n      \"expected_inference\": \"What the target reader can now infer.\",\n      \"uncertainty\": \"Alternative interpretation or confidence limit.\"\n    }\n  ],\n  \"open_reader_questions\": [],\n  \"macguffin_changes\": [],\n  \"open_threads\": [],\n  \"resolved_threads\": [],\n  \"uncertainties\": []\n}\n```\n\nKeep `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.\n\n3. Preview the deterministic ledger change:\n\n```bash\npython3 \"<skill-dir>/scripts/update_story_ledger.py\" \\\n  --project-root . --input /tmp/chapter-state.json --dry-run\n```\n\n4. After verifying every item against the chapter, rerun without `--dry-run`.\n5. Rebuild the next chapter's context pack and rerun the continuity audit.\n\nNever record speculation as a fact. Put ambiguity in `uncertainties` with competing interpretations.\n\n## Token Discipline\n\n- Use the ledger for stable outcomes and recent chapter excerpts for voice and immediate physical continuity.\n- Retrieve by explicit source links before lexical relevance.\n- Keep hard invariants even when they appear unrelated to the current scene.\n- Trim prose before trimming rules, obligations, clue states, or character knowledge.\n- Recompute context after an accepted chapter rather than carrying a stale chat summary forward.\n- Treat token estimates as conservative approximations; inspect the generated pack size before expanding it.\n\n## Completion Gate\n\nDo not finish a story-planning or chapter task until:\n\n- the target change advances the story promise or intentionally complicates it;\n- escalation changes kind or cost, not only volume;\n- the chapter exit differs materially from its entry;\n- the target reader's exit model differs intentionally from its entry model;\n- every required reader inference has prior reader-visible evidence or a recoverable causal bridge;\n- intended ambiguity preserves local orientation and is not accidental confusion;\n- all used knowledge, rules, objects, and relationships have provenance;\n- setups and payoffs remain tracked;\n- the output language and prose style match the author's contract;\n- structural audit errors are resolved;\n- the chapter exists directly under `chapters/` with synchronized filename, frontmatter, H1, and required body sections;\n- Draft prose follows the paragraph, dialogue, emphasis, literal-text, and\n  scene-break Markdown contract;\n- new canon is reflected in source files and the reviewed story ledger when applicable.\n"
}