/interactive-fiction

name: interactive-fiction
description: This skill should be used when the user asks to "write a branching story", "interactive fiction", "choose your own adventure", "plan the branches", "choice graph", "add a choice", "gamebook", "Twine", "Ink", "draft a branch", "where the branches rejoin", "add an ending", "unreachable chapter", "path continuity", "state-differs-by-path", or wants to plan, draft, or revise a story project whose chapters carry `choices`. NOT for turning a finished linear book into an interactive edition in Ink or Twine (use adaptation).

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`](../../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.`).