Team Split Assessment

Plan Under Review

File: documentation/src/content/docs/roadmap/completed/item-image-upload/ux-design/use-cases/specification.md
Date: 2026-03-25

Complexity Analysis

Factor	Value	Threshold	Assessment
Total tasks (47 stories + 17 MDX + mock data + verification)	~70	15	Over
Distinct phases with sequential dependencies	4 (Waves 1–4) + cleanup	2	Over
Distinct persona types needed	2 (front-end-engineer, quality-reviewer)	4	Under
Estimated working directories	1 (ux-prototype worktree)	1	At threshold
Cross-cutting concerns (handoffs, gates)	4 (wave gates with VRT)	1	Over
Tasks with external validation (builds, tests, VRT)	4 (one per wave)	5	Under

Qualitative factors:

Context window pressure: HIGH. 47 story files + 17 description MDX files is significant. Each scenario directory requires a description.mdx, stories, and a Playground. A single team lead tracking all of this will exhaust context.
Error blast radius: MODERATE. Wave gates isolate failures — a broken story in Wave 2 doesn’t invalidate Wave 1 stories. But within a wave, stories share mock data and composition patterns.
Natural phase boundaries: CLEAR. The 4 waves have explicit entry/exit criteria and component dependency ordering.

Recommendation

Split into 5 runs — one per specification wave plus a sidebar clean-up. Each wave has clear component dependencies, a coherent set of stories, and a wave gate that must pass before the next wave begins. The waves are already defined in the specification with explicit scope boundaries.

Proposed Runs

Run	Directory	Description	Story Files	MDX Files	Personas	Est. Complexity
1	`run-1-view-and-fallback/`	GEN-MEDIA-0003 View Entity Image + mock data + verification of existing stories	10	5	fe, qr	Low-Medium
2	`run-2-input-and-validation/`	GEN-MEDIA-0001 scenarios 0002–0004 (input routing, formats, URL validation)	16	3	fe, qr	Medium
3	`run-3-preview-and-confirm/`	GEN-MEDIA-0001 scenarios 0005–0006 (preview, crop, confirm, persist)	10	3	fe, qr	Medium
4	`run-4-integration/`	End-to-end flows, grid inline edit, removal, REF::ITM integration stories	16	6	fe, qr	High
5	`run-5-cleanup/`	Sidebar `preview.ts` top-level section reorder	0 (mods)	0	fe, qr	Low

Artifact Flow

Run 1 ──────────────────────────────────────────────────────────────────────────►
  Produces: _shared/mock-data.ts, view-entity-image/ stories + MDX,
            verified existing stories still pass, VRT baselines updated
                │
Run 2 ──────────────────────────────────────────────────────────────────────────►
  Consumes: _shared/mock-data.ts (from Run 1)
  Produces: set-entity-image/ input-* + formats-* + url-* stories
                │
Run 3 ──────────────────────────────────────────────────────────────────────────►
  Consumes: _shared/mock-data.ts, input story patterns (from Runs 1-2)
  Produces: set-entity-image/ preview-* + confirm-* + MDX stories
                │
Run 4 ──────────────────────────────────────────────────────────────────────────►
  Consumes: all prior stories and patterns
  Produces: set-image-* + grid-inline-edit-* + remove-* + REF::ITM stories + MDX,
            entity-media.mdx section description

Risk Analysis

Splitting mitigates:

Context window exhaustion from tracking 47 stories simultaneously
Cascading failures — a broken wave gate stops before contaminating downstream work
VRT snapshot management — each wave takes its own baselines incrementally

Coordination overhead is minimal because:

All 4 runs operate in the same repository (ux-prototype)
All runs use the same persona set (front-end-engineer + quality-reviewer)
Handoffs are filesystem-only (committed story files + updated VRT baselines)
The specification is the single source of truth — no inter-run design decisions

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	Should Runs 1 and 2 execute in parallel (no dependency between view stories and input stories)?	(a) Sequential — simpler, mock data from Run 1 feeds Run 2. (b) Parallel — faster, each run creates its own mock data slice.	(a) Sequential — mock data is shared and small; overhead of parallel coordination isn’t justified for the time savings.	Pending
2	Should the reference vendored story (set-image-during-creation.stories.tsx) be in Run 4 or deferred to a follow-up?	(a) Include in Run 4. (b) Defer — it’s a baseline, not the project goal.	(a) Include — it’s a single file wrapping the vendored component, minimal effort.	Pending