Janpeter Visser
bae0d478ea
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>
64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# 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
|
||
```
|