Document type: story

Table of Contents

This page defines the story document type — one entry in the document types taxonomy. The general contract every document follows (frontmatter, state, linking, tags) lives on the taxonomy page; this page carries only what is specific to story.

1. Contract

Implements
loading, declaration, recording. See Regulatory Functions.
Folder
versions/<v>/<sprint>/<story_slug>/story.org
Title
Story: <human readable title>. The Story: = prefix is added by the codegen automatically when the type is =story.
Level
s2
TODO vocabulary
BACKLOG STARTED | DONE ABANDONED (no DISCOVERED or BLOCKED at story level).
How to create
see New story in the codegen recipe.
Required sections (in this order)
  • Blurb — opens with This page documents a [[id:699A8D45-B67E-4D3E-9206-24FA17C51ADA][story]] in [[id:<parent_id>][<parent_title>]].
  • * Goal — the user-visible outcome.
  • * Status — table; rows State / Parent sprint / Now / Waiting on / Next / Last touched.
  • * Acceptance — when is this story done?
  • * Documents — optional; required once the story produces any document beyond its own tasks. A table naming every document the story produced or reasons from, with its kind and purpose. Durable documents deliberately do not link back to the story, so this table is the only way in when the history is genuinely needed. See design § "The story is the hub".
  • * Tasks — id-links to its child tasks, in execution order.
  • * Decisions — distilled from plans as tasks land.
  • * Out of scope — what we explicitly chose not to include.

1.1. Cross-sprint stories — predecessor and successor

A story belongs to exactly one sprint. When work cannot fit a single sprint, the story closes DONE with whatever landed and a successor story is created in the next sprint. Optional frontmatter fields link the two: 

#+predecessor: <id-of-prior-story>    ; on the successor: where the work began
#+successor:   <id-of-next-story>     ; on the predecessor: where the work continues

Both fields carry the target story's :ID: (not its slug — slugs may collide across sprints).

Inline body conventions:

On the successor
Continued from: [[id:<predecessor>][...]] sits immediately after the parent-sprint link, so a reader sees the history at the top.
On the predecessor
a Continued in: [[id:<successor>][...]] note goes into * Decisions, recorded when the successor is created.

The successor's slug is the original slug suffixed with _continued, _phase_2, or similar — pick whichever reads better in context.

Audit verifies bidirectional links: every #+predecessor has a matching #+successor pointing back.

1.2. Story frontmatter (additions on top of the standard set)

#+category: <feature|housekeeping|enabler>
#+predecessor: <id-of-prior-story>
#+successor:   <id-of-next-story>
  • #+category: — required; one of feature, housekeeping, or enabler. Drives velocity tracking (see ** Story categories in * Tags above).
  • #+predecessor: / #+successor: — optional; used on stories that span sprints (see *** Cross-sprint stories above for full conventions).

The #+category: field classifies the story's intent so velocity metrics can be sliced by type (see ** Story categories in * Tags above). It is required on every story created from sprint 18 onward.

Emacs 29.3 (Org mode 9.6.15)