Story Example

The following is a complete, well-formed *.story.mdoc file. It illustrates tone, structure, and the relationship between the role and features attributes and the narrative body.

type: story
id: user-saves-first-bookmark
title: A User Saves Their First Bookmark
status: ready
tags: [onboarding, core-loop]
context:
  - role/user
  - feature/add-bookmark


{% story role="user" features="feature/add-bookmark feature/view-bookmarks" scope="public agent" %}

I've just come across an article I know I won't finish reading now. My coffee break is almost over.

I paste the URL into the input at the top of the page and press Save. The bookmark appears instantly at the top of my list — title already filled in, the site's favicon showing next to it. No form, no modal, no confirmation screen. It's just there.

Later that evening I open the app again. The article is waiting for me exactly where I left it. I tap it and the original page loads.

That's the whole loop. Find something, save it, come back to it. It should feel that effortless every time.

{% /story %}

What makes this example good

Single journey, single goal: The story follows one actor through one loop without branching into edge cases.
First-person, concrete: “I paste the URL” rather than “the user submits the form”. Describes experience, not implementation.
Covers both features naturally: add-bookmark and view-bookmarks appear in the narrative without forcing them.
No requirements stated: The story does not introduce new requirements — those belong in the feature documents.
Short: A story that fits on one screen is a good story. Longer is not better.