user-stories

1# User stories
2 
3Screens show what an app looks like. Stories say what a person does with
4it. You build and test stories, not screens.
5 
6Read `docs/BRIEF.md`, `docs/research/*.md`, and `docs/screens/INDEX.md`
7where they exist. Write `docs/STORIES.md`.
8 
9## Story format
10 
11```markdown
12### S-012 Complete a task with the keyboard
13As the user, I select a task and press Command-Return to complete it.
14Screens: 01-inbox.png, 02-today.png
15Depends: S-004
16Acceptance:
17- [snap] The circle fills and the row fades out within half a second.
18- [self] An "Undo" banner shows for five seconds; Command-Z also undoes it.
19- [unit] A recurring task moves to its next date.
20Status: todo
21```
22 
23- One action per story. "Rename a project from its context menu", not
24  "Manage projects".
25- Every acceptance line starts with how it is checked: `[snap]` snapshot,
26  `[unit]` unit test, `[self]` self-test, `[manual]` a person must try it.
27  "Works well" is not checkable.
28- `Screens:` links reference screenshots, so `improve-loop` knows what to
29  compare. Without a reference app, name the snapshot pages that will show
30  the story. A panel, sheet, or menu needs its own snapshot page.
31- `Depends:` (optional) lists stories that must be done first.
32- Keep a control and the only surface that shows it in one story: a
33  highlighting field that lives only in the quick-add panel ships with the
34  panel.
35- Status: `todo`, `doing`, `done`, or `dropped`.
36 
37## Milestones
38 
39Each milestone ends with an app the user can use for a day.
40…