draft-story

Draft Story

Turn a requirement into one implementable story. This is the upfront direction gate: cheap to get right here, expensive to discover wrong after a build.

Core principle: A story is done when an engineer with no prior context could implement it without guessing.

Output

Write ONE flat Markdown file in the stories namespace (physical path from core-config.yaml, default docs/stories/): <slug>.md — <slug> is a kebab handle from the title. No folders, no epic.story numbering. Produce exactly these sections (with frontmatter) and nothing more.

---
origin: <stable short handle of the requirement this story came from>
depends_on: [] # slugs of same-origin stories whose Produces this story Consumes
touches: [] # every path in File Map (Create + Modify), as written there
---

# <Story title>

## Goal

One sentence: what this delivers and for whom.

## Constraints

Hard rules this story must respect, one per line, copied verbatim — no
paraphrase (version floors, allowed/forbidden dependencies, naming and copy
rules, platform requirements). Every section below implicitly includes these.

## Acceptance Criteria

- AC1: <observable, testable condition>
- AC2: ...
  Every AC must be checkable by a test or a human looking at a result.

## File Map

- Create: <exact/path>
- Modify: <exact/path>
- Test: <exact/path>

## Interfaces

- Consumes: <signatures this story relies on from existing code>
- Produces: <signatures later work will rely on — exact names and types>

## UI Reference (only if the story touches UI)

Link to the front-end spec / design and name the exact screens or components in
scope. Omit this section entirely for non-UI stories.

## Out of Scope

What this story deliberately does NOT do.

Rules

• One story, one coherent deliverable. If it spans independent subsystems, split into separate stories — each its own <slug>.md in the stories namespace, all sharing the same origin so the set is queryable as one group.
• Flat, no hierarchy. One file per story in the stories dir. Grouping is the origin field (a query the AI runs), never a folder. Order comes from Interfaces (dependencies), never from a number.
• Dependencies and footprint are explicit. depends_on is derived from Interfaces: a story that Consumes a signature another same-origin story Produces depends on it — nothing else qualifies. touches repeats the File Map so a team run can detect two stories that would edit the same file without opening either. Both are empty lists when there is nothing to list, never omitted.
• No placeholders. "Add validation", "handle errors", "TBD" are failures. State the actual condition.
• Acceptance criteria are observable. "Works well" is not an AC. "Returns 400 with {error:'Email required'} for empty email" is.
• Stay at spec altitude. Describe what must be true, not how to code it. Implementation is the implement skill's job.
• Constraints are verbatim. Copy each hard rule exactly from its source — a paraphrased limit is a changed limit.
• UI Reference only when there is UI. Omit the section for non-UI stories; never leave it as an empty placeholder.