User stories
Screens show what an app looks like. Stories say what a person does with
it. You build and test stories, not screens.
Read docs/BRIEF.md, docs/research/*.md, and docs/screens/INDEX.md
where they exist. Write docs/STORIES.md.
Story format
### S-012 Complete a task with the keyboard
As the user, I select a task and press Command-Return to complete it.
Screens: 01-inbox.png, 02-today.png
Depends: S-004
Acceptance:
- [snap] The circle fills and the row fades out within half a second.
- [self] An "Undo" banner shows for five seconds; Command-Z also undoes it.
- [unit] A recurring task moves to its next date.
Status: todo
- One action per story. "Rename a project from its context menu", not
"Manage projects".
- Every acceptance line starts with how it is checked:
[snap] snapshot,
[unit] unit test, [self] self-test, [manual] a person must try it.
"Works well" is not checkable.
Screens: links reference screenshots, so improve-loop knows what to
compare. Without a reference app, name the snapshot pages that will show
the story. A panel, sheet, or menu needs its own snapshot page.
Depends: (optional) lists stories that must be done first.
- Keep a control and the only surface that shows it in one story: a
highlighting field that lives only in the quick-add panel ships with the
panel.
- Status:
todo, doing, done, or dropped.
Milestones
Each milestone ends with an app the user can use for a day.
- M1 Core loop: the one thing the app is for, end to end. Data
survives a restart.
- M2 Organize: the main structure, sidebar pages, moving items.
- M3 Time: dates, Today and Upcoming, recurrence, reminders.
- M4 Speed: quick-add panel, global shortcut, natural language input,
keyboard navigation, search, menu commands.
- M5 System: menu bar, Share menu, Shortcuts, notifications, CLI.
- M6 Polish: drag and drop, context menus, empty states, icon, settings.
Rename milestones to fit the app. Inside a milestone, stories that others
depend on come first.
Seed data
Every attribute the seed data sets (symbols, colors, notes) is something a
story lets the user create in the app. Otherwise snapshots show features
no one can use.
Leave things out
Drop what exists only for other people or for the vendor: accounts,
sharing, teams, integrations, upgrade prompts, gamification. List them
under ## Dropped, one line each, so the decision is visible.
UX notes
For each M1 story that adds a screen, an action, or words, call the Skill
tool with ux-design. It adds a UX: block under the acceptance lines and
starts docs/GLOSSARY.md, so every story uses the same names. Later
milestones get their UX notes in improve-loop, just before they are built.
Size check
M1 has 5 to 10 stories. Over 60 stories in total means version one is too
big: move stories to ## Later.
Done when every main job in the brief, every "Version one: yes" row in the
research matrix, and every screen in the index maps to a story or a
Dropped line, and every M1 story with UI has a UX: block.
1---2name: user-stories3description: Prioritized backlog of user stories with checkable acceptance criteria (docs/STORIES.md) for a macOS app, built from a brief, research, or screen index. Use after app-brief or clone, or when the user asks for user stories, a backlog, a feature list, or "what do we build first".4metadata:5 source: https://skillmd.com/skills/tuyv/user-stories6---78# User stories910Screens show what an app looks like. Stories say what a person does with11it. You build and test stories, not screens.1213Read `docs/BRIEF.md`, `docs/research/*.md`, and `docs/screens/INDEX.md`14where they exist. Write `docs/STORIES.md`.1516## Story format1718```markdown19### S-012 Complete a task with the keyboard20As the user, I select a task and press Command-Return to complete it.21Screens: 01-inbox.png, 02-today.png22Depends: S-00423Acceptance:24- [snap] The circle fills and the row fades out within half a second.25- [self] An "Undo" banner shows for five seconds; Command-Z also undoes it.26- [unit] A recurring task moves to its next date.27Status: todo28```2930- One action per story. "Rename a project from its context menu", not31 "Manage projects".32- Every acceptance line starts with how it is checked: `[snap]` snapshot,33 `[unit]` unit test, `[self]` self-test, `[manual]` a person must try it.34 "Works well" is not checkable.35- `Screens:` links reference screenshots, so `improve-loop` knows what to36 compare. Without a reference app, name the snapshot pages that will show37 the story. A panel, sheet, or menu needs its own snapshot page.38- `Depends:` (optional) lists stories that must be done first.39- Keep a control and the only surface that shows it in one story: a40 highlighting field that lives only in the quick-add panel ships with the41 panel.42- Status: `todo`, `doing`, `done`, or `dropped`.4344## Milestones4546Each milestone ends with an app the user can use for a day.47481. **M1 Core loop**: the one thing the app is for, end to end. Data49 survives a restart.502. **M2 Organize**: the main structure, sidebar pages, moving items.513. **M3 Time**: dates, Today and Upcoming, recurrence, reminders.524. **M4 Speed**: quick-add panel, global shortcut, natural language input,53 keyboard navigation, search, menu commands.545. **M5 System**: menu bar, Share menu, Shortcuts, notifications, CLI.556. **M6 Polish**: drag and drop, context menus, empty states, icon, settings.5657Rename milestones to fit the app. Inside a milestone, stories that others58depend on come first.5960## Seed data6162Every attribute the seed data sets (symbols, colors, notes) is something a63story lets the user create in the app. Otherwise snapshots show features64no one can use.6566## Leave things out6768Drop what exists only for other people or for the vendor: accounts,69sharing, teams, integrations, upgrade prompts, gamification. List them70under `## Dropped`, one line each, so the decision is visible.7172## UX notes7374For each M1 story that adds a screen, an action, or words, call the Skill75tool with `ux-design`. It adds a `UX:` block under the acceptance lines and76starts `docs/GLOSSARY.md`, so every story uses the same names. Later77milestones get their UX notes in `improve-loop`, just before they are built.7879## Size check8081M1 has 5 to 10 stories. Over 60 stories in total means version one is too82big: move stories to `## Later`.8384Done when every main job in the brief, every "Version one: yes" row in the85research matrix, and every screen in the index maps to a story or a86`Dropped` line, and every M1 story with UI has a `UX:` block.