janpeter visser 6d0940cc5e docs: add story-with-ui-component pattern + CLAUDE.md reference

Documents the mandatory 3-task pattern (Helper / Component / Integration)
for stories introducing UI components. Cites the 2026-05-02 Velocity story
as the anti-pattern and the Foundation Sprint Health story as the blueprint.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-02 17:27:19 +02:00

2.7 KiB

Raw Blame History

Patroon: Story met UI-component

Probleemstelling

Zonder een afsluitende Integration-task leverden agent-batches helpers en components die nooit in de UI verschenen. De Velocity-story (cmomu4xpq001obortc9enpvfa) van 2 mei 2026 is het concrete incident: Helper (getVelocity) en Component (VelocityChart) werden gebouwd en getest, maar zonder Integration-task bleef de /insights-pagina leeg.

Verplicht patroon

Elke story die een *-component.tsx introduceert moet minimaal drie tasks bevatten:

#	Type	Doel	Bestand
1	Helper	Data-aggregatie of business-logic	`lib/<domain>/<helper>.ts`
2	Component	Presentational layer	`app/.../<component>.tsx`
3	Integration	Wire component in page + verify renders	`app/.../<route>/page.tsx`

De Integration-task heeft verify_required: ALIGNED — de agent-verify moet de page.tsx in de diff terugzien voordat de job als done wordt geaccepteerd.

Blueprint: Foundation Sprint Health-story

De story cmomu0txi0016borthlautjjp ("Foundation: route, recharts, sprint-dates migration, chart-colors helper") volgt dit patroon correct:

Tasks 1–3 — Helper-tasks (sprint-dates migration, chart-colors, route scaffolding)
Task 4 — "Sprint-info-strip + integratie in /insights page" — sluit de loop: component wordt in page.tsx geïmporteerd en gerenderd

Gebruik deze story als blueprint bij het aanmaken van nieuwe PBI's met UI-componenten.

Anti-patroon

De Velocity-story had alleen Helper + Component. De Integration-task ontbrak:

✅ cmomu54pw001pbortedjhg2l8  Helper: getVelocity
✅ cmomu5bht001qbortlcq15arc  Component: VelocityChart
❌ (ontbreekt)                Integration: wire VelocityChart into /insights page

Resultaat: de component bestaat en compileert, maar is nergens te zien.

Reviewchecklist bij PBI-creatie

Voordat een PBI met UI-features naar de backlog gaat:

Elke story die een *-component.tsx introduceert heeft een Integration-task
Integration-task raakt minimaal app/(app)/<route>/page.tsx
Integration-task heeft verify_required: ALIGNED (of een equivalent verify-gate)
Integration-task title volgt het formaat: Integration: wire <ComponentName> into <route>

Template (kopieer bij elke nieuwe UI-story)

Task 1 — Helper: <beschrijving data-aggregatie>
  Bestand: lib/<domain>/<helper>.ts
  Tests: minimaal 3 scenario's

Task 2 — Component: <beschrijving component>
  Bestand: app/(app)/<route>/components/<component>.tsx
  Tests: TypeScript + render-smoke

Task 3 — Integration: wire <ComponentName> into /<route> page
  Bestanden: app/(app)/<route>/page.tsx
  verify_required: ALIGNED
  Done when: component verschijnt in de browser zonder empty-state op dev-data

2.7 KiB Raw Blame History Unescape Escape