User Story Template

template-user-story Template

active template

Project

User Story Template

A user story is a first-class note in pal-e-docs that captures who needs what and why. Stories are the "why" leg of the traceability triangle — they give meaning to tickets and architecture decisions. Every ticket on a board should trace back to a story (or be explicitly foundational work with no story: label).

User stories were previously inline table rows on project pages. Promoting them to notes gives them permanence, linkability, and the ability to survive across multiple boards. A single story might drive work across 3 boards and 20 tickets over months.

Note type: user-story (new type)

Required Sections

Every user-story note follows this structure. The h2 title uses the story: prefix for scannability.

Section Reference

Section	Required	Purpose
<code>## story: {title}</code>	Yes	Human-readable story name. Always prefixed with <code>story:</code> for scannability.
<code>### Role</code>	Yes	Who this story serves. Name the persona and, where applicable, the real person (e.g., "Coach (Marcus)").
<code>### Key</code>	Yes	Short hyphenated label used in <code>story:</code> labels on tickets. Must be unique within the project. This is the string that appears in <code>story:roster-view</code> on board items.
<code>### Want</code>	Yes	The desire. Format: "As a <strong>{role}</strong>, I want to <strong>{action}</strong>". Keep it to one sentence.
<code>### So That</code>	Yes	The motivation. Format: "So that <strong>{outcome}</strong>". This is why the story matters — it drives prioritization.
<code>### Acceptance Criteria</code>	Yes	Bulleted checklist of verifiable outcomes. Each criterion should be testable — an agent or QA reviewer can look at the deployed result and check the box.
<code>### Success Metric</code>	Yes	How we measure whether this story is truly fulfilled. Quantitative where possible (e.g., "100% of coaches can view roster within 2 clicks").
<code>### Related Architecture</code>	Yes	Links to <code>arch-*</code> notes this story touches. This is the story-to-architecture edge of the traceability triangle.
<code>### Related</code>	Yes	Links to the parent project page, boards that reference this story, and any other relevant notes.

Naming Convention

Field	Convention	Example
Slug	<code>story-{project}-{key}</code>	<code>story-westside-roster-view</code>
Title	Descriptive, no prefix needed (slug carries the prefix)	"Coach Roster View"
Note type	<code>user-story</code>	—
Tags	<code>user-story</code> (topic tag), plus <code>active</code> or <code>draft</code> or <code>archived</code>	<code>user-story,active</code>
Project	Same project as the parent project page	<code>westside</code>
Parent	<strong>None.</strong> Stories are project-level, not children of boards or other notes.	—
Status	<code>active</code> (in play), <code>draft</code> (being shaped), <code>archived</code> (delivered or abandoned)	<code>active</code>

Story Lifecycle

Stories Survive Boards

A critical distinction: stories are not tied to a single board. A story like "Coach Roster View" might generate tickets across three boards over two months:

board-westside — initial API endpoint ticket (story:roster-view,arch:basketball-api)
board-210-roster-feature — decomposition board for the frontend work
board-westside again — a follow-up bug fix six weeks later (story:roster-view,type:bug)

The story note is the thread that ties all of this together. When you want to understand the full history of a capability, you read the story note and search for story:{key} across boards.

Relationship to template-ticket

The template-ticket defines the story: label convention. The Key field in this template is the value that appears after story: on board items. The connection:

User-story note defines ### Key as roster-view
Board items carry the label story:roster-view
To find all tickets serving a story, filter board items by that label
To understand what a story: label means, look up story-{project}-{key}

Previously, story keys lived only in inline tables on project pages (see template-project-page, User Stories section). Those tables still exist as the index — a quick-reference of all stories for a project. But the detail, acceptance criteria, and cross-board traceability now live in the story note.

Relationship to template-board

The template-board has a ### User Stories section that scopes which stories a decomposition board serves. Those references should link to story notes:

Role	Key	Story Note	Success Metric
Coach	<code>roster-view</code>	<code>story-westside-roster-view</code>	100% of coaches can view roster within 2 clicks

The board's User Stories table is a scoped subset — it tells you which stories this particular board advances. The story notes themselves are the full record.

The Traceability Triangle

User stories are one vertex of the triangle defined in template-ticket:

With stories as first-class notes:

Story → Architecture: the ### Related Architecture section links to arch-* notes
Story → Tickets: board items carry story:{key} labels; the story note's ### Related section links to relevant boards
Architecture → Story: architecture notes can reference which stories they serve
Ticket → Story: the story: label on any board item resolves to story-{project}-{key}

Migration from Inline Tables

Existing projects have user stories as rows in the project page's ### User Stories table. To migrate:

For each row in the table, create a story-{project}-{key} note using this template
Keep the summary table on the project page as an index (Role, Key, Story Note link, Success Metric)
Move detailed acceptance criteria from Forgejo issues or implicit knowledge into the story note
Link architecture notes in the story's ### Related Architecture section

The project page table becomes a directory; the story notes become the source of truth.

What This Template Does NOT Cover

Ticket structure → see template-ticket. Tickets reference stories; they are not stories.
Board structure → see template-board. Boards scope which stories they serve.
Architecture diagrams → see template-project-page and convention-architecture-ids. Stories link to arch notes; they don't contain diagrams.
Forgejo issue format → see template-issue. The issue is the dev agent spec; the story is the human intent.

template-ticket — board item conventions, story: label definition, traceability triangle
template-board — decomposition boards reference story notes in their User Stories section
note-conventions — canonical reference for note types, slugs, tags, and linking
template-project-page — project page User Stories table (the index that links to story notes)
template-issue — Forgejo issue format (execution spec for a single ticket)
convention-architecture-ids — canonical arch: component ID naming
sop-board-workflow — column semantics for boards that execute story work

User Story Template