Story vs Braindump
The difference between a note to self and a contract between product, design, and engineering. Titles that read as implementation, ACs tangled with technical notes, and the kind of ticket a new joiner has no chance with.
Refactor useAuthController to support new session structure
Users stay signed in across tab reloads
A title that names the implementation tells you what the engineer plans to do, not what users will get. A new joiner reads it and learns nothing about the product. Save implementation language for the subtasks or the PR description.
The title names a user-visible outcome a designer, PM, or new engineer can reason about cold. Same work underneath, but the framing answers what changes for whoever is on the other end.
Users stay signed in across tab reloads
Users stay signed in across tab reloads
Refactoring a helper is not an acceptance criterion, it is engineering work. Mixed lists make QA's job impossible: half the items are not testable from the outside, half look like work that already happened.
Acceptance criteria describe outcomes. Implementation steps live in subtasks where they belong. QA can verify each AC by clicking, without asking the engineer what the cookie helper does.
Improve report exports
Needs updates in exporter.ts and reportTable. @priya knows the context. See thread in #squad-reports from last Tuesday.
Analysts export filtered reports without opening them
Analysts run the same filter across 30 reports a week. Today they have to open each report to export, which costs them roughly an afternoon.
Pointing at a Slack thread and a person's name puts the why entirely in two places that will disappear: the thread will scroll out of search, and the person will rotate off the team.
The right side names the actor, the outcome, and the cost they pay today. Six months from now, when the team has rotated, the ticket still answers 'why did we do this?' on its own.
Customers see the new tax line on the invoice
Depends on the tax service being live. Mark says it should be ready next sprint.
Customers see the new tax line on the invoice
Blocked by TAX-117 (tax service /v1/quote). Once that is shipped, this story unblocks.
Mentioning a name and a service in prose is not a link. Nothing in the planning board updates when the dependency moves, and 'next sprint' has the half-life of one slipped commitment.
The dependency is a linked ticket key, not a hallway conversation. When TAX-117 moves the planning board can see the unblock automatically and the next refinement can pull this story without hunting for context.
Editors see autosave confirmation while drafting
Add a debounced effect on draftStore that calls /api/drafts/autosave every 5s. Wire the response into useToast. Watch out for the SSR hydration mismatch we hit in EDIT-201.
Editors see autosave confirmation while drafting
A description full of file names, hooks, and edge-case warnings is a note to self in disguise. Anyone reading cold has to pattern-match through the codebase to figure out what the user gets.
Outcome on the front, mechanism in the subtasks. Product can demo what changed, engineering still has the implementation breadcrumbs, and the SSR caveat is captured where it will be read by whoever picks up the work.
Fix the onboarding bug from last quarter
See the Q3 retro doc. We agreed Tomas would own this. The 8-step page in the wizard should "do what we said in the meeting."
New users finish onboarding without losing progress on a refresh
The wizard currently stores progress only in memory. Funnel data shows ~12% of users drop off between steps 4 and 5, correlating with refresh events.
Cross-referencing a retro doc, a name, and a meeting outcome makes the ticket only readable by people who were there. Six months later, none of those references will resolve.
A new joiner reads three lines and is oriented: who suffers, what changes, why it matters, and roughly the size of the problem. The funnel datum makes the priority defensible without needing to find the meeting it came from.
Switch from useEffect to useSyncExternalStore in CartContext
The current implementation re-renders on every browser tab focus. New API gives us tearing-free reads.
Cart contents stay in sync across multiple browser tabs
A title that begins with 'Switch from X to Y' is a refactor in disguise. It might be the right refactor, but it is not a story until someone outside engineering can describe what changes for the user.
The right ticket describes what shoppers experience and why it matters. The implementation choice (useSyncExternalStore, store wiring) lives in the code review, not the title. The same engineer can do the same work, but everyone else can read along.