Back to roadmap
US-0920
Email Templates
SHIPPEDAI drafted the designLast verified 4 min ago
User story
real-timewebsocketfan-out
Channels & integrations · auto-detected from this story
In-appSEmailTSMSSSlack
Acceptance criteria
3 / 3 verified
Each scenario is run as a Playwright test by the QA agent
Scenario 1: User receives notification on a critical event Verified
Givena user is logged into the platform
Andthey have notification preferences enabled
Whena critical event occurs in their workspace
Thena real-time notification appears within 2 seconds
Andthe notification contains event type, timestamp, and source
Scenario 2: Notification respects user preferences Verified
Givena user has disabled email notifications
Whena critical event triggers a notification
Thenonly in-app and push notifications are sent
Andno email is dispatched
Scenario 3: Fails gracefully on WebSocket disconnect Verified
Givena user's WebSocket connection drops
Whena critical event occurs
Thenthe notification is queued for retry
Andthe user sees a reconnecting indicator
Andqueued notifications are delivered on reconnect
Spec quality · craft learnings applied
8/10 passingGeneralisable rules the agent applies to every spec — they grow from review feedback & flaky scenarios, and act as a self-improving linter.
Assert one outcome per scenarioAtomicity
Each scenario asserts a single outcome
One trigger per scenarioAtomicity
Every scenario has exactly one trigger
Keep implementation out of Given/When/ThenClarity
Scenario 3 names an implementation detail (“WebSocket”)
Scenarios describe behaviour, not mechanism — naming the tech couples the spec to today's design and ages it.
Make every outcome machine-checkableTestability
Outcomes are concrete and observable
Bound time-sensitive outcomesTestability
“Fails gracefully on WebSocket disconnect” states a delivery outcome with no time bound
“Delivered on reconnect” isn't testable without a limit — add “within N seconds” so the QA agent can assert it.
Pair every happy path with a failure pathCoverage
An explicit failure / edge scenario is present
Assert the negative spaceCoverage
At least one scenario asserts the negative
State actor, capability and benefitClarity
Story names actor, capability and benefit
One promise per storyScope
The story makes a single promise
Keep the slice thinScope
3 scenarios — a thin, shippable slice
Learnings applied · from the library
Real-time features need a reconnect scenariohigh
Any real-time/websocket delivery feature must include an explicit offline → deliver-on-reconnect acceptance scenario, or it regresses under deploys.
Learned from US-1042 S3 (added then regressed) · INC-204
Preference changes need an audit trailmedium
When users can change delivery preferences, add a scenario asserting changes are recorded and respected immediately.
Learned from US-1042 design review