Overview

Audience: UX and Front-End Engineers (with Product Owner collaboration) Scope: Implementing Storybook stories from documented Use Cases for any GEN::ENT-DA entity domain Reference project: Business Affiliate UX (PR #52 on Arda-cards/ux-prototype)

Overview

This guide describes the end-to-end workflow for turning a set of documented Use Cases and Scenarios (in the documentation repository) into a complete Storybook story suite (in ux-prototype). You drive the process through four phases, collaborating with the Product Owner at approval gates.

Phase	Name	Your Role	PO Role	Duration Estimate
A	Scope Analysis & Story Specification	Analyze docs, draft specs	Decides scope, reviews specs	1 session
B	Wave Planning & Plan Generation	Build dependency graph, plan waves	Approves wave structure	1 session
C	Agent Team Implementation	Orchestrate agents, verify waves	Monitors, resolves blockers	1-3 sessions
D	Stabilization, PR & Documentation	Stabilize CI, open PR	Reviews PR, approves merge	1 session

Approval gates between phases are on by default. The PO may waive specific gates at project start by declaring: “Phases A-B are gated, C-D are autonomous” (or any combination). Waived gates still produce their artifacts — they just don’t block progression.

Prerequisites

Before starting, ensure:

Use Case documentation exists in documentation/src/content/docs/product/use-cases/ for the target entity domain. Each Use Case should have numbered scenarios (e.g., REF::BA::0001::0001.UC).
General behaviors are documented — the entity domain implements GEN::ENT-DA (or GEN::ENTSUB for subordinate entities), and those generic behaviors are already specified.
The ux-prototype repository has the Storybook infrastructure in place (Vite, React, Tailwind, MSW, fullAppProviders decorator).
A product release name is known (e.g., “MVP2”) for priority annotation of in-scope scenarios.

Phase A: Scope Analysis & Story Specification

Goal: Define what’s in scope, what’s deferred, and produce detailed specifications for each story.

A.1 — Read the Documentation

Read all Use Case documents for the target domain, cross-referencing with:

The generic entity behaviors (GEN::ENT-DA, GEN::ENTSUB)
Any existing Storybook stories in ux-prototype
The backend API shape (for MSW handler design)

A.2 — Make Scope Decisions

For each Use Case and scenario, decide: in scope, deferred, or simplified. Collaborate with the Product Owner on these decisions.

Document each decision using the Scope Decision format:

### SD-N: <Title>

<One-sentence decision statement>

**Rationale**: <Why this decision was made — user value, technical complexity, dependency reasoning>

Typical decisions for an entity-domain project:

Category	Question	Example from BA project
Layout	Detail panel structure (tabs vs. scroll)?	SD-1: Continuous scroll with collapsible sections
Tabs	Which detail tabs are in scope?	SD-2: Single Details tab only
Subordinates	Subordinate entity management?	SD-3: Silent VENDOR assignment, no role UI
Delete	Referential integrity warnings?	SD-4: Simple confirmation, no warnings
History	Version history and restore?	SD-5: Deferred entirely
API	Which MSW handlers are needed?	SD-6: Lookup handler for name search

Template: Scope Analysis Example: Scope Decisions

A.3 — Build the Scenario Inventory

List every scenario from the documentation, marking each as in-scope or deferred. This becomes the source of truth for story count and wave sizing.

A.4 — Write Story Specifications

For each in-scope scenario (or group of related scenarios), write a story specification covering:

Story variants: Interactive, Stepwise, Automated (for multi-step workflows) or single-variant with play function (for single-interaction stories)
Shared infrastructure: Types, mock data, MSW handlers, shared components
Play function assertions: Step-by-step interaction sequence with specific queries and expected outcomes
File organization: Directory structure under src/use-cases/reference/<domain>/

Template: Story Specification Example: Story Spec — Pagination

A.5 — Write Application Conventions

Document domain-specific decisions that apply across all stories:

MSW handler registry (routes, latencies, error shapes)
Shared component registry (what’s reused, what’s new)
Mock data requirements (count, variety, edge cases)
Naming conventions for files and Storybook titles

Template: Application Conventions

Gate A: Get PO sign-off on scope decisions and story specifications.

Exit criteria:

All scope decisions documented with rationale
Scenario inventory complete with in/out classification
Story specifications written for all in-scope stories
Application conventions document captures shared infrastructure plan

Phase B: Wave Planning & Plan Generation

Goal: Organize stories into dependency-ordered waves and generate individual implementation plans.

B.1 — Define the Dependency Graph

Identify which stories depend on shared infrastructure built by other stories. Common patterns:

Foundation story: Builds all _shared/ infrastructure (types, mock data, MSW handlers, page component). Always Wave 0.
Critical unlock: A single story that builds a shared component (e.g., detail drawer) that multiple later stories depend on. Usually a dedicated wave.
Parallel-safe stories: Stories that create new files without modifying shared infrastructure. Can run in parallel with worktrees.
Sequential stories: Stories that modify the same shared files (e.g., the page component). Must run in sequence.

B.2 — Assign Stories to Waves

Organize into waves following the dependency graph:

Wave 0 (foundation) ─── Wave 1 (parallel: browse/search stories)
       │
       └────────────── Wave 2 (sequential: critical unlock)
                            │
                            ├── Wave 3 (sequential: create + edit happy paths)
                            │
                            └── Wave 4 (parallel: error variants)

For each wave, specify:

Stories included
Parallelism: How many agents can work simultaneously
Worktree strategy: Whether agents need isolated worktrees or work on the integration branch
Exit criteria: What must pass before the next wave starts

Template: Implementation Plan Example: Wave Structure

B.3 — Generate Individual Plans

For each story, generate a detailed implementation plan covering:

Preconditions: What infrastructure must exist
Element classification: Reused as-is, modified, created
File inventory: Create/modify/delete
Implementation steps: Numbered steps with verification
Risk notes: What could go wrong and mitigations

Template: Story Plan Example: Individual Plan — Pagination

B.4 — Audit Plans

After generating plans in batches, run audit passes to verify:

No infrastructure gaps (every handler/component referenced is actually built by a prior story)
No file conflicts between parallel stories in the same wave
Consistent naming and import paths

Gate B: Get PO sign-off on wave structure and implementation plan.

Exit criteria:

Dependency graph documented
All stories assigned to waves with parallelism strategy
Individual plans generated for all stories (except pre-existing Wave 0)
Audit reports show no gaps or conflicts

Phase C: Agent Team Implementation

Goal: Execute the plans wave by wave, producing working Storybook stories.

C.0 — Setup

Create the integration branch: <username>/<domain>-use-cases from main
Configure permissions: Add worktree paths to .claude/settings.json if using parallel agents
Set up progress tracking: Initialize the Progress Tracker

C.1 — Execute Waves

For each wave:

Launch agents with the wave’s plans
- Parallel waves: Use worktrees (<domain>-impl-worktrees/<story-name>)
- Sequential waves: Work directly on the integration branch
Verify wave completion: npm run lint, npx tsc --noEmit, npm run test
Merge worktree branches into the integration branch
Commit: feat(<domain>): implement Wave N — <summary>

Agent Personas and Skills

This workflow uses the following agent personas and skills. Agent definitions and skills are maintained in the workspace repository; the shared location of these definitions may change in the future.

Personas:

Persona	Purpose
`front-end-engineer`	Implements React components, stories, MSW handlers, play functions
`quality-reviewer`	Reviews code for standards compliance (read-only)
`team-lead`	Orchestrates multi-agent waves, manages worktrees

Skills:

Skill	Purpose
`launch-team`	Launches agent teams against task plans with worktree isolation
`ui-component`	React component creation conventions (separated concerns, Storybook integration)
`unit-tests-frontend`	Frontend testing patterns (Jest, RTL, coverage)

C.2 — Polish Pass

After all waves complete:

Add Table of Contents MDX page linking all stories
Add Storybook sidebar navigation (spec-ID prefixes, sort ordering)
Add addon-links for cross-story navigation
Verify sidebar structure matches the story specification

Gate C: Get PO sign-off on implementation output (stories render correctly, play functions pass).

Exit criteria:

All stories implemented per specifications
All waves pass verification (lint, tsc, test)
Progress tracker shows 100% completion
Sidebar structure matches specification

Phase D: Stabilization, PR & Documentation

Goal: Get CI green, merge the PR, and annotate the documentation with scope decisions.

D.1 — CI Stabilization

Storybook play functions that pass locally often fail in CI due to environment differences. The table below summarizes the most common issues; see CI Stabilization Patterns for the full catalog with code examples.

Issue	Symptom	Fix
AG Grid virtualization	Rows in DOM but not “visible”	Don’t assert `toBeVisible()` after `findByText` on grid cells
AG Grid buffer rows	Row count off by 1-2	Never assert exact row counts
AG Grid re-renders	Elements disappear after mutations	Wrap post-mutation assertions in `waitFor()`
Sonner toast animation	`findByText` succeeds, `toBeVisible()` fails	Two-step: find element, then `waitFor(() => expect(el).toBeVisible())`
Radix dropdown portals	`canvas.findByRole('menuitem')` fails	Use `screen.findByRole('menuitem')` — Radix portals to `document.body`
Duplicate text matches	”Found multiple elements”	Scope with `within(drawer)` after re-querying the container
`userEvent.tripleClick`	Method doesn’t exist	Use `userEvent.clear()` instead

D.2 — Open PR and Monitor

Push the integration branch
Open PR against main with:
- Story inventory table
- Architecture decisions summary
- Testing notes (what’s covered, known limitations)
Run mandatory pre-push gate: npm run lint, npx tsc --noEmit, npm run test
Monitor CI checks, fix failures, re-push

D.3 — Handle Review Comments

For each reviewer comment:

Read and understand the concern
Reply with explanation or commit a fix
Resolve the thread

D.4 — Annotate Documentation

After the PR is merged, update the documentation repository:

Add scenario-level Priority annotations to each Use Case scenario:
- In-scope scenarios: **Priority**: <release-name>
- Deferred scenarios: **Priority**: Undefined
- Simplified scenarios: **Priority**: <release-name> -- simplified: <note>
Add an overview page summarizing all scenarios in two tables (in-scope vs. deferred) with links to each scenario anchor
Update CHANGELOG.md with a new version entry

D.5 — Write Retrospective

Capture the complete project lifecycle in a retrospective document:

Phases executed with key decisions
Technical insights discovered during CI stabilization
Process improvements for future projects

Gate D: Get PO sign-off on PR merge and documentation updates.

Exit criteria:

Agent Team Sizing Heuristics

When planning parallel waves, use these heuristics:

Split by file, not by statement count. If one agent gets 3 unique pages and another gets 7 identical components, the pages agent will bottleneck.
Weight mock complexity heavily. Files requiring unique MSW handler strategies take longer than files reusing existing handlers.
Discount template-replicable work. Seven identical typeahead stories finish much faster than seven unique page stories with the same line count.
Give giant files their own agent. Files over 1000 lines should get a dedicated agent to avoid serialization.
Formula: number of unique source files × mock complexity factor. This is a better proxy than estimated statement count.

Quick Reference: Artifact Checklist

Artifact	Template	Produced In
Scope Analysis	Scope Analysis	Phase A
Story Specifications	Story Specification	Phase A
Application Conventions	Application Conventions	Phase A
Implementation Plan	Implementation Plan	Phase B
Individual Story Plans	Story Plan	Phase B
Progress Tracker	Progress Tracker	Phase C
Retrospective	(free-form)	Phase D

Project Directory Layout

When you create a project using this workflow, the working directory should follow this structure:

<project-dir>/
├── scope-analysis.md                # Phase A output
├── story-specifications.md          # Phase A output
├── application-conventions.md       # Phase A output
├── implementation-project-plan.md   # Phase B output
├── implementation-progress.md       # Phase C tracker
├── planning-progress.md             # Phase B tracker
├── plans/                           # Phase B output
│   ├── <ID>_<Story_Name>.md         # One per story
│   └── run-N-audit-report.md        # Audit reports
└── retrospective.md                 # Phase D output