Interactive Fiction

Interactive Fiction

Overview

Plan, draft, and revise a branching book: a story project whose chapters are passages joined by choices in their frontmatter. The chapters and their choices are the source of truth. story continuity follows the paths of choices, and story build --format twee or --format ink turns the project into a playable Twine or ink story.

This skill owns books written to branch from the start. Turning an existing linear book into an interactive edition (a branch map drawn from its scenes, then a copied project) belongs to the adaptation skill; once that edition project exists, draft and revise its chapters here.

Prerequisites

A story project with story.md in the root. For a new book, start it with the story-init skill first. Read story.md (language, pov, tense, form, status, ifid) and chapters/_index.md, then the choices of every chapter: together they are the graph. A small example is examples/the-gull-rock-light, a branch-and-bottleneck story with two endings.

When to Use

• Planning a choice graph: structure, branch points, rejoins, endings
• Writing or changing choices entries
• Drafting a chapter on a branch, at a rejoin, or at an ending
• Revising a branching book, and reading state-differs-by-path, unreachable-chapter, and the other branching findings
• Building the book as Twine or ink
• NOT for converting a linear book (use adaptation), drafting a linear chapter (use chapter-writing), or a linear continuity audit (use revision-continuity). Prose craft inside a passage still comes from scene-craft and line-editing

How The Graph Works

• Each chapter is one passage. Its choices are where the reader can go:

  choices:
    - text: Search the rocks for Tobias
      to: chapter-02
    - text: Climb the tower to the lamp
      to: chapter-03

• The lowest-numbered chapter is the start.

• Once any chapter has choices, the links are exactly the choices: a chapter with none is an ending, and a chapter that leads on to one place needs a single choice (text: Continue). With no choices anywhere the book is linear again.

• text becomes the link text: no [, ], |, ->, <-, or line break, and no final <. Quote it if it looks like a number.

• to is a chapter id. It may be the chapter itself (a loop) or, while planning, a chapter-NN with no file yet; the builds need every target written.

Workflow

1. Plan The Choice Graph

Agree the shape with the user before drafting; see references/choice-graph.md for the structures, choice design, and numbering. Then:

1. Draw the graph: every passage, every choice, every rejoin, every ending. Count passages and endings against target-words and the form.

2. Number chapters so each choice leads to a higher number, except a loop back. The promise, question, and clue ledgers, the clock and route checks, story pacing, and the story diagram and story series lifelines still read chapter numbers, so this keeps them close to the paths.

3. Scaffold each passage as an outline chapter with its POV and cast, then add its choices by hand (story add does not write them):

   story add chapter 'The Landing' --number 1 --status outline --pov ada-fenn --character ada-fenn --hook decision --path .

4. Check the skeleton before writing prose. story links . warns unreachable-chapter for every chapter no path from the start reaches, and errors on a choice to a missing chapter, except a chapter-NN with no file yet, which it allows as scheduled. So a typo such as chapter-09 for chapter-08 passes: compare every to with the planned passage list by hand, and once every passage has a file, run story build . --format twee, which refuses any choice to a missing chapter.

5. Record the state choices set that the CLI does not track (flags, trust, items the reader can carry down one branch) in notes/branch-map.md, a working file the CLI ignores: a table of each flag, the chapter that sets it, and the chapters that read it.

2. Draft A Passage

Draft with the chapter-writing workflow (outline, approval, prose, post-write updates), with these differences:

• Run story context chapter-NN --path . for every passage. In a branching book it holds only what was drafted and learned on a path to that chapter, so a sibling branch never leaks in.
• On a branch: the passage may use everything on the paths that lead to it, and nothing from its sibling.
• At a rejoin: the context lists the scenes of every branch that leads there. Read each incoming chapter and write only what is true on every path: who is where, who is hurt, what the reader has seen. Facts are marked known when any incoming path teaches them, so check each fact the rejoin uses against every branch. A detail that differs by path stays out of the rejoin prose, or is carried by a flag in the built Twine or ink file (see Build).
• At a branch point: end on the decision (hook: decision) and make each choice meaningful, informed, and acknowledged in the passage it leads to.
• At an ending: no choices, hook: resolution, and an ending that pays off the path that reached it. Name it as an ending in the prose if the book's style does (THE END.).

After saving the passage, record continuity as chapter-writing does, following references/path-continuity.md for the branching rules: deaths and revivals, one knowledge-state entry per branch for a fact learned on two branches, and the continuity/state.md snapshot.

3. Revise A Branching Book

Use revision-continuity for the passes, plus these checks:

• Reachability: fix every unreachable-chapter by adding a choice that leads there, from a passage the user agrees (see Hard Rules). Removing the chapter deletes its file and its drafted prose, so offer it only as an option, and put the whole removal to the user for one approval:
  1. Take a snapshot (see Draft Snapshots in the revision-continuity skill).
  2. remove chapter refuses while scene files point at the chapter, so dry-run each of its scenes: story remove scene <scene-id> --path . --dry-run.
  3. Dry-run the chapter: story remove chapter <id> --path . --dry-run. While the chapter still has scenes, this prints only that refusal. It also refuses while a died-in, since, or learned-in field, or a progression's from, names the chapter, so search the project for the chapter id and list those references too: each needs another chapter before the removal can run.
  4. Show the user every file the dry runs would update and delete, and every reference that blocks the removal. Only with their explicit approval, repoint the blocking references, remove the scenes, then remove the chapter. It drops the choices that led to the chapter and warns which chapters became endings.
  5. If the chapter removal is still refused after the scenes are gone, stop and ask the user: go on with the next fix, or restore the snapshot (story snapshot --restore <name> --path . --dry-run first, as the revision-continuity skill describes).
• Endings: list the chapters with no choices. Each should be a deliberate ending. A chapter that lost its last choice in a revision is an accidental ending: give it a choice.
• Loops: the CLI does not check that a loop has a way out. Trace every loop and confirm a choice leaves it.
• Path continuity: run story continuity . and read the branching findings in references/path-continuity.md. Then do the hand checks there for what the checker reads by chapter number. Branching books in ../story-maintenance/references/continuity-checks.md says which continuity, knowledge, context, timeline, and grid results follow the paths and which go by chapter number.
• Renumbering: story move chapter, story split, and story merge rewrite every to that named an old id. Split and merge work here only on chapters with no choices, and merge only when no choice leads to the second chapter; restructure anything else by hand. A split gives its first half a Continue choice that leads to the rest, so offer the user other words for it. None of them edits prose, so reread the passages for chapter numbers in the text.
• Rejoin prose: after changing a branch, reread every rejoin it leads to and confirm the prose still holds on that path.