Requirements Specification
Overview
Problem Statement
Santa's workshop delivers cookies to children all over the world using a manual workflow, which leads to long delivery times and the wrong cookies reaching children. Children have no way to request a cookie or see where it is, and elves have no shared view of the work in progress.
Goal
Give children a simple way to request and track cookies, and give the workshop one place to approve, bake, pack and deliver every request. Success means fewer baking and delivery mistakes and a shorter time from request to delivery.
Success Metrics
| Metric | Target | How measured |
|---|---|---|
| Request drop-off rate | Minimal drop-off | Analytics events per request step |
| Time to approval | Reduced vs. baseline | Timestamp: Request Created → Approved / Denied |
| Time to delivery | Reduced vs. baseline | Timestamp: Approved → Delivered |
| Baking mistakes | Reduced vs. baseline | Packaging rejections logged in request history |
| Delivery mistakes | Reduced vs. baseline | Failed / misdelivered requests logged in history |
Out of Scope
- Full system administration (user account management, roles screens), which is deferred to a second pass.
- Exception workflows (failed delivery, return to kitchen).
- Search and filtering on the dashboard.
- A written naughty / nice criteria guide for dispatchers.
Users
| Persona | Description | Primary Need |
|---|---|---|
| Child | Young end user with limited reading and typing ability; uses a parent's or family device | Ask for a favorite cookie and see when it will arrive |
| Dispatch Elf | Reviews every incoming request against naughty / nice criteria | Approve or reject requests quickly and consistently |
| Baking Elf | Manages oven queues | Know what to bake next and mark it done |
| Packaging Elf | Boxes approved, baked cookies | See what is ready to pack and confirm the right cookie went in the box |
| Delivery Elf | Handles routes and final drop-off | Know where each box goes and record delivery |
Assumptions & Constraints
- Assumptions:
- The first release is a concept prototype for trial sessions alongside the current workflow, not a full replacement.
- Elves sign in with shared or pre-created accounts for the trial.
- Children track requests by order ID, without an account.
- Constraints:
- Must be built with an existing design system to keep prototyping fast and consistent.
- Child-facing screens must work for young readers (large targets, minimal text entry).
- Dependencies:
- Naughty / nice status data from Dispatch.
- Address data must be accurate enough for delivery routing.
User Stories
Epic A: Child Request & Tracking
US-01: Submit a cookie request
As a child, I want to enter my name and choose my cookie type, so that the elves know what to bake and who to send it to.
Priority: Must
Acceptance Criteria
- AC1: Given I am on the landing page, when I start a request, then I am asked for my name.
- AC2: Given I have entered my name, when I continue, then I can verify my address.
- AC3: Given I have entered my details, when I continue, then I can choose one cookie from: Chocolate Chip, Chocolate Chocolate Chip, Oatmeal without Raisins, Snickerdoodle, Sugar Cookie, Gingerbread.
- AC4: Given I submit the request, when it is created, then I see a confirmation with my order ID and the pending status.
- AC5 (error case): Given a required field (name, address, cookie) is empty, when I submit, then I see a plain-language message next to the field and the request is not created.
US-02: Track a request by order ID
As a child, I want to look up my request by order ID, so that I can see where my cookie order is.
Priority: Must
Acceptance Criteria
- AC1: Given a valid order ID, when I look it up, then I see the current workflow state and a timeline of past states.
- AC2: Given an elf moves my request to a new state, when I refresh the tracker, then the new state is shown.
- AC3: Given my request was denied, when I view it, then I see a friendly message rather than an error.
- AC4: Given my request was updated, the screen auto-updates every 5 minutes.
- AC5 (error case): Given an order ID that does not exist, when I look it up, then I see an order not found message and can try again.
Epic B: Workshop Dashboard & Workflow
US-03: View all requests in one dashboard
As an elf (any role), I want a central dashboard of all cookie requests and their status, so that I can see what needs my attention.
Priority: Must
Acceptance Criteria
- AC1: Given I am signed in, when I open the dashboard, then I see every request with its order ID, child name, cookie and current state.
- AC2: Given requests exist in several states, when I view the dashboard, then I can see counts per workflow state.
- AC3: Given no requests exist, when I open the dashboard, then I see an empty state instead of a blank table.
US-04: View request details and history
As an elf, I want to open a request and see all of its details and history, so that I can do my step correctly.
Priority: Must
Acceptance Criteria
- AC1: Given I select a request, when its details open, then I see the full data model.
- AC2: Given a request has changed state, when I view its history, then each action is listed with a timestamp.
US-05: Approve or deny a request
As a Dispatch Elf, I want to approve or deny each incoming request, so that only nice children's requests go to the kitchen.
Priority: Must
Acceptance Criteria
- AC1: Given a request is pending, when I approve it, then it moves to baking and the action is logged in history.
- AC2: Given a request is pending, when I deny it, then it is closed, the child's tracker shows it was not approved, and the action is logged.
- AC3: Given I review a request, when I view it, then the child's naughty / nice status is visible.
US-06: Move a request through the workflow
As a Baking, Packaging or Delivery Elf, I want to move a request to the next state when my step is done, so that the next team knows it is ready and the child can follow along.
Priority: Must
Acceptance Criteria
- AC1: Given a request is in my step, when I mark it complete, then it moves to the next state in order: Baking → Packaging → Delivery → Delivered.
- AC2: Given a state change happens, when it is saved, then it is logged in history with a timestamp and the child's tracker updates.
- AC3: Given automatic transitions are turned on for a step, when its completion condition is met, then the request moves on without manual input.
- AC4 (error case): Given a request is not in my step, when I try to move it, then the action is unavailable.
Epic C: Second Pass (Post-MVP)
US-07: Manage user accounts and roles (RBAC)
As a workshop administrator, I want to create, edit and remove elf accounts and assign roles, so that each elf only sees the screens and actions they need.
Priority: Should
Acceptance Criteria
- AC1: Given I am an administrator, when I create, read, update or delete a user, then the change is saved and logged.
- AC2: Given a user has a role, when they sign in, then they only see the actions allowed for that role.
US-08: Manage request history and retention
As a workshop administrator, I want to clear out request history that is no longer needed, so that we keep only what we need and meet legal requirements.
Priority: Should
Acceptance Criteria
- AC1: Given history is older than the retention period, when I run cleanup, then it is removed and the cleanup is logged.
US-09: Search and filter requests
As an elf, I want to search and filter requests by most data model fields, so that I can find a specific request quickly.
Priority: Could
Acceptance Criteria
- AC1: Given many requests, when I search by order ID, then only matching requests are shown.
- AC2: Given many requests, when I search by child name, then only matching requests are shown.
- AC3: Given many requests, when I filter by state, then only matching requests are shown.
- AC4: Given many requests, when I filter by cookie, then only matching requests are shown.
- AC5: Given many requests, when I filter by naughty / nice status, then only matching requests are shown.
US-10: Handle exception states
As a Delivery or Packaging Elf, I want to mark a request as Failed Delivery or Return to Kitchen, so that problems are fixed instead of lost.
Priority: Could
Acceptance Criteria
- AC1: Given a delivery fails (for example, an address error), when I mark it Failed Delivery, then I must add a reason and the request is flagged on the dashboard.
- AC2: Given a cookie is wrong or damaged, when I mark it Return to Kitchen, then it goes back to baking with a note.
US-11: Documented naughty / nice criteria
As a Dispatch Elf, I want written naughty / nice criteria available while I review, so that my decisions are consistent.
Priority: Could
Acceptance Criteria
- AC1: Given I am reviewing a request, when I open the criteria, then I see them without leaving the request.
US-12: User activity log
As a workshop administrator, I want a full log of user activity, so that I can audit who did what and when.
Priority: Could
Acceptance Criteria
- AC1: Given any user action, when it happens, then it is logged with the user, action and timestamp.
Non-Functional Requirements
| ID | Category | Requirement | Acceptance Criteria | | NFR-01 | Accessibility | Meets WCAG 2.1 AA | Passes WCAG audit with 0 critical issues | | NFR-02 | Usability | Child screens suit young readers | Large touch targets (at least 44×44px); cookie choices shown with pictures as well as text | | NFR-03 | Privacy | Children's personal data is protected | Name and address are only visible to signed-in elves; the public tracker only shows status | | NFR-04 | Auditability | Every state change is traceable | 100% of transitions have a history entry with action and timestamp | | NFR-05 | Browser support | Latest 2 versions of major browsers | Verified in Chrome, Safari, Firefox, Edge |
Prioritized MVP List
The smallest set of stories needed to run trial sessions alongside the current workflow.
| Rank | ID | Story | Priority | Why it's in MVP |
|---|---|---|---|---|
| 1 | US-01 | Submit a cookie request | Must | Core job; nothing else works without a request |
| 2 | US-03 | View all requests in one dashboard | Must | Elves need one shared view of the work |
| 3 | US-05 | Approve or deny a request | Must | Required gate before baking |
| 4 | US-06 | Move a request through the workflow | Must | Drives the whole fulfillment process |
| 5 | US-04 | View request details and history | Must | Elves need the details (and allergy notes) to do their step correctly |
| 6 | US-02 | Track a request by order ID | Must | Delivers the child-facing value and reduces "where's my cookie?" questions |
Post-MVP Backlog
| ID | Story | Priority | Reason deferred |
|---|---|---|---|
| US-07 | Manage user accounts and roles | Should | Trial can run on pre-created accounts; needed before full rollout |
| US-08 | Manage request history and retention | Should | Not needed until real data builds up; needed for legal compliance |
| US-09 | Search and filter requests | Could | Trial volume is small enough to scan |
| US-10 | Handle exception states | Could | Validate the happy path first |
| US-11 | Documented naughty / nice criteria | Could | Needs input from Dispatch before writing |
| US-12 | User activity log | Could | Request history covers trial needs |
MVP Release Criteria
- All Must stories meet their acceptance criteria
- All NFRs pass
- Workshop lead sign-off to start trial sessions