Add component lifecycle + retroactive review plan
- docs/reference/component-lifecycle.md: 10-stage quality gate sequence (build → stories → audit/critique/harden → fix → polish → present → iterate → normalize → preflight → commit) - docs/reference/retroactive-review-plan.md: Plan to review 30+ existing components using condensed process (~3.5 sessions) - Updated /build-atom, /build-molecule, /build-organism to include internal QA stages automatically - CLAUDE.md: added lifecycle reference as critical rule #8 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -19,4 +19,10 @@ Use the component-builder agent to handle this task. The user wants to build the
|
||||
6. ALL visual values MUST come from the MUI theme — never hardcode
|
||||
7. Write comprehensive Storybook stories covering all states
|
||||
8. Verify the component renders in Storybook
|
||||
9. Update all memory files when done
|
||||
9. **Run internal QA** (stages 3-5 from `docs/reference/component-lifecycle.md`):
|
||||
- Run `/audit` — fix all P0/P1 issues
|
||||
- Run `/critique` (skip for simple utility atoms like Divider)
|
||||
- Run `/harden` (skip for display-only atoms like Typography, Badge)
|
||||
- Run `/polish` — final alignment, spacing, transitions
|
||||
10. Present to user with summary and scores
|
||||
11. Update all memory files when done
|
||||
|
||||
@@ -20,4 +20,11 @@ Use the component-builder agent to handle this task. The user wants to build the
|
||||
7. ALL visual values MUST come from the MUI theme — never hardcode
|
||||
8. Write comprehensive Storybook stories with realistic content
|
||||
9. Verify the component renders in Storybook
|
||||
10. Update all memory files when done
|
||||
10. **Run internal QA** (stages 3-5 from `docs/reference/component-lifecycle.md`):
|
||||
- Run `/audit` — fix all P0/P1 issues
|
||||
- Run `/critique` — fix all P0/P1 issues
|
||||
- Run `/harden` — check edge cases for interactive molecules
|
||||
- Run `/polish` — final alignment, spacing, transitions
|
||||
- Run `/typeset` if text-heavy (cards, form fields)
|
||||
11. Present to user with summary and scores
|
||||
12. Update all memory files when done
|
||||
|
||||
@@ -21,4 +21,14 @@ Use the component-builder agent to handle this task. The user wants to build the
|
||||
8. ALL visual values MUST come from the MUI theme — never hardcode
|
||||
9. Write comprehensive Storybook stories with realistic page-level content
|
||||
10. Verify the component renders in Storybook
|
||||
11. Update all memory files when done
|
||||
11. **Run internal QA** (stages 3-5 from `docs/reference/component-lifecycle.md`):
|
||||
- Run `/audit` — fix all P0/P1 issues
|
||||
- Run `/critique` — fix all P0/P1 issues
|
||||
- Run `/harden` — check all edge cases (organisms handle real data)
|
||||
- Run `/polish` — final alignment, spacing, transitions
|
||||
- Run `/typeset` if text-heavy
|
||||
- Run `/adapt` — responsive check (organisms are layout components)
|
||||
- Run `/quieter` if the organism handles sensitive moments (pricing, forms, errors)
|
||||
- Run `/clarify` if the organism has decision points or complex information
|
||||
12. Present to user with summary and scores
|
||||
13. Update all memory files when done
|
||||
|
||||
@@ -40,7 +40,8 @@ professional, trustworthy, and calm. Users are often in distress.
|
||||
5. **Always update docs/memory/** after completing work — log what was done, decisions made, and open questions
|
||||
6. **Run `npm run build:tokens`** after any token JSON change
|
||||
7. **Verify in Storybook** before marking any component done
|
||||
8. **Commit and push after completing each unit of work** — see Git workflow below
|
||||
8. **Follow the component lifecycle** — see `docs/reference/component-lifecycle.md` for the full quality gate sequence (build → QA → polish → present → iterate → normalize → preflight → commit)
|
||||
9. **Commit and push after completing each unit of work** — see Git workflow below
|
||||
|
||||
## Git workflow
|
||||
|
||||
|
||||
154
docs/reference/component-lifecycle.md
Normal file
154
docs/reference/component-lifecycle.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# Component Lifecycle
|
||||
|
||||
Every component follows this lifecycle. Skills are run in order — each stage must
|
||||
pass before moving to the next. This prevents ad-hoc back-and-forth tweaking.
|
||||
|
||||
## The Stages
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. BUILD /build-atom, /build-molecule, /build-organism │
|
||||
│ 2. STORIES /write-stories │
|
||||
│ 3. INTERNAL QA /audit → /critique → /harden │
|
||||
│ 4. FIX Fix all P0 and P1 issues from stage 3 │
|
||||
│ 5. POLISH /polish → /typeset → /adapt │
|
||||
│ 6. PRESENT Show to user in Storybook │
|
||||
│ 7. ITERATE User feedback → targeted fixes (1-2 rounds) │
|
||||
│ 8. NORMALIZE /normalize (cross-component consistency) │
|
||||
│ 9. PREFLIGHT /preflight │
|
||||
│ 10. COMMIT git add → commit → push │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## When to use each skill
|
||||
|
||||
### Stage 1 — BUILD
|
||||
**Skill:** `/build-atom`, `/build-molecule`, `/build-organism`
|
||||
**When:** Starting a new component. The skill handles reading memory files,
|
||||
checking the registry, creating the file structure, and writing the code.
|
||||
**Output:** Component .tsx + stories .tsx + index.ts
|
||||
|
||||
### Stage 2 — STORIES
|
||||
**Skill:** `/write-stories`
|
||||
**When:** If the build skill didn't produce comprehensive stories, or if stories
|
||||
need updating after changes. Stories must cover: default, all variants, all
|
||||
sizes, disabled, loading, error, long content, minimal content.
|
||||
**Output:** Complete story coverage in Storybook
|
||||
|
||||
### Stage 3 — INTERNAL QA (run before showing to user)
|
||||
Three skills, run in this order:
|
||||
|
||||
1. **`/audit`** — Technical quality (a11y, performance, theming, responsive, design).
|
||||
Produces a score out of 20 and P0-P3 issues.
|
||||
2. **`/critique`** — UX design review (hierarchy, emotion, cognitive load, composition).
|
||||
Produces a score out of 40 and priority issues.
|
||||
3. **`/harden`** — Edge cases (error states, empty states, loading, boundaries, disabled).
|
||||
Ensures robustness for real-world data.
|
||||
|
||||
**Exit criteria:** No P0 issues remaining. P1 issues documented.
|
||||
|
||||
### Stage 4 — FIX
|
||||
**No skill — just implementation work.**
|
||||
**When:** Fix all P0 and P1 issues found in stage 3.
|
||||
Then re-run the relevant check (e.g., if the fix was an a11y issue, re-run
|
||||
`/audit` to verify). Don't re-run all three unless the fixes were broad.
|
||||
**Exit criteria:** P0 = 0, P1 = 0 (or documented as intentional with rationale).
|
||||
|
||||
### Stage 5 — POLISH
|
||||
Three skills, run as needed based on the component:
|
||||
|
||||
1. **`/polish`** — Visual alignment, spacing, transitions, copy, micro-details.
|
||||
Run on every component.
|
||||
2. **`/typeset`** — Typography: hierarchy, line length, weight, readability.
|
||||
Run on text-heavy components (cards, forms, detail panels).
|
||||
3. **`/adapt`** — Responsive: touch targets, overflow, mobile spacing.
|
||||
Run on layout components (organisms, cards, navigation).
|
||||
|
||||
**Optional context-specific skills:**
|
||||
- **`/quieter`** — Run on components that handle sensitive moments (pricing,
|
||||
commitment steps, error messaging). Not needed for utility atoms.
|
||||
- **`/clarify`** — Run on components with decision points or complex information
|
||||
(FuneralFinder, ArrangementForm, PricingTable). Not needed for simple atoms.
|
||||
|
||||
### Stage 6 — PRESENT
|
||||
**No skill — show in Storybook.**
|
||||
**When:** All internal QA is done. The component should be in its best state
|
||||
before the user sees it. Present with a brief summary of what it does, key
|
||||
design decisions, and scores from audit/critique.
|
||||
|
||||
### Stage 7 — ITERATE
|
||||
**No skill — targeted fixes from user feedback.**
|
||||
**When:** User reviews in Storybook and gives feedback. This should be 1-2 rounds
|
||||
max because stages 3-5 caught most issues. If feedback requires major changes,
|
||||
go back to stage 1. Minor tweaks stay here.
|
||||
**Exit criteria:** User approves.
|
||||
|
||||
### Stage 8 — NORMALIZE
|
||||
**Skill:** `/normalize`
|
||||
**When:** After user approval, run against the component's tier (e.g., `/normalize atoms`)
|
||||
to check it's consistent with its peers. This catches: token access patterns (D031),
|
||||
transition timing, focus styles, spacing methods, displayName, exports.
|
||||
**Note:** This is a cross-component check, so it's most valuable after several
|
||||
components in a tier are done. Can be batched.
|
||||
|
||||
### Stage 9 — PREFLIGHT
|
||||
**Skill:** `/preflight`
|
||||
**When:** Before committing. Verifies TypeScript, Storybook build, token sync,
|
||||
hardcoded values, exports, ESLint, Prettier.
|
||||
**Exit criteria:** All critical checks pass.
|
||||
|
||||
### Stage 10 — COMMIT
|
||||
**No skill — git workflow.**
|
||||
Stage, commit with descriptive message, push. Husky runs lint-staged automatically.
|
||||
|
||||
---
|
||||
|
||||
## Shorthand for quick reference
|
||||
|
||||
| Stage | Skill(s) | Who triggers | Blocking? |
|
||||
|-------|----------|-------------|-----------|
|
||||
| Build | /build-{tier} | User requests | — |
|
||||
| Stories | /write-stories | Auto in build | — |
|
||||
| Internal QA | /audit → /critique → /harden | Agent (auto) | P0 = blocking |
|
||||
| Fix | — | Agent | Until P0/P1 = 0 |
|
||||
| Polish | /polish + /typeset + /adapt | Agent (auto) | — |
|
||||
| Present | — | Agent → User | — |
|
||||
| Iterate | — | User feedback | 1-2 rounds |
|
||||
| Normalize | /normalize | Agent (batch OK) | — |
|
||||
| Preflight | /preflight | Agent (auto) | Critical = blocking |
|
||||
| Commit | — | Agent | — |
|
||||
|
||||
**"Agent (auto)"** means I should run these proactively without being asked.
|
||||
**"Agent (batch OK)"** means it can be deferred and run across multiple components.
|
||||
|
||||
---
|
||||
|
||||
## Which skills are optional vs required?
|
||||
|
||||
| Skill | Required for | Optional for |
|
||||
|-------|-------------|-------------|
|
||||
| /audit | All components | — |
|
||||
| /critique | All molecules + organisms | Simple atoms (Button, Divider) |
|
||||
| /harden | All interactive components | Display-only atoms (Typography, Badge) |
|
||||
| /polish | All components | — |
|
||||
| /typeset | Text-heavy components | Icon-only or structural components |
|
||||
| /adapt | Layout components, organisms | Small inline atoms |
|
||||
| /quieter | Sensitive context components | Utility atoms |
|
||||
| /clarify | Decision-point components | Simple atoms |
|
||||
| /normalize | All (batched by tier) | — |
|
||||
| /preflight | All (before commit) | — |
|
||||
|
||||
---
|
||||
|
||||
## For existing components
|
||||
|
||||
Components built before this lifecycle was defined can be retroactively
|
||||
reviewed using a condensed process:
|
||||
|
||||
1. `/normalize {tier}` — Scan the tier for consistency issues
|
||||
2. `/audit {component}` — Score each component
|
||||
3. Fix P0/P1 issues only (don't re-polish what's already working)
|
||||
4. `/preflight` → commit
|
||||
|
||||
This is lighter than the full lifecycle because these components have already
|
||||
been through user review and iteration.
|
||||
137
docs/reference/retroactive-review-plan.md
Normal file
137
docs/reference/retroactive-review-plan.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# Retroactive Review Plan
|
||||
|
||||
Components built before the workflow upgrade (2026-03-27) haven't been through
|
||||
the full quality gate lifecycle. This plan reviews them using a lighter process
|
||||
focused on catching real issues, not re-polishing what already works.
|
||||
|
||||
## Approach
|
||||
|
||||
Use the condensed review process from component-lifecycle.md:
|
||||
1. `/normalize {tier}` — Scan the tier for cross-component consistency
|
||||
2. `/audit {component}` — Score each component (only those scoring < 16/20 need fixes)
|
||||
3. Fix P0/P1 issues only
|
||||
4. `/preflight` → commit
|
||||
|
||||
## Priority Order
|
||||
|
||||
Review bottom-up: atoms first (they're the foundation everything builds on),
|
||||
then molecules, then organisms. Within each tier, prioritise by usage —
|
||||
components used by many others matter more than standalone ones.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Atoms (foundation layer — highest priority)
|
||||
|
||||
### Step 1.1 — Normalize all atoms
|
||||
Run `/normalize atoms` once to get a cross-component consistency report.
|
||||
Expected findings: token access patterns (D031), transition timing, focus
|
||||
styles. Fix all issues in a single batch commit.
|
||||
|
||||
### Step 1.2 — Audit each atom
|
||||
Run `/audit` on each atom. Components already audited in previous sessions have
|
||||
scores on record. Focus on those that scored < 16/20 or were never audited.
|
||||
|
||||
| Atom | Last Audit Score | Priority |
|
||||
|------|-----------------|----------|
|
||||
| Button | — (not formally audited) | High (most-used atom) |
|
||||
| Typography | — | Medium (display-only) |
|
||||
| Input | — | High (forms foundation) |
|
||||
| Card | — | High (used by all cards) |
|
||||
| Badge | — | Medium (fixed in D031) |
|
||||
| Chip | — | Low (minimal wrapper) |
|
||||
| Switch | — | Low (minimal wrapper) |
|
||||
| Radio | — | Low (minimal wrapper) |
|
||||
| IconButton | — | Low (minimal wrapper) |
|
||||
| Divider | — | Low (minimal wrapper) |
|
||||
| Link | — | Low (minimal wrapper) |
|
||||
|
||||
**Estimated effort:** 1 session for normalize + audit of high/medium priority atoms.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Molecules (composition layer)
|
||||
|
||||
### Step 2.1 — Normalize all molecules
|
||||
Run `/normalize molecules` for cross-component consistency.
|
||||
|
||||
### Step 2.2 — Audit + critique priority molecules
|
||||
Run `/audit` and `/critique` on molecules with real layout complexity.
|
||||
|
||||
| Molecule | Last Scores | Priority |
|
||||
|----------|------------|----------|
|
||||
| ProviderCard | Critique 33/40 (v2 iteration) | Medium (user-approved) |
|
||||
| VenueCard | Critique 33/40 | Medium (user-approved) |
|
||||
| SearchBar | Critique 35/40 | Low (high scores already) |
|
||||
| ServiceOption | — | Medium (used by ServiceSelector) |
|
||||
| AddOnOption | — | Medium (similar pattern to ServiceOption) |
|
||||
| StepIndicator | — | Low (display-only) |
|
||||
| LineItem | Audit 19/20 | Low (excellent score) |
|
||||
| ProviderCardCompact | — | Medium (newer, less reviewed) |
|
||||
|
||||
**Estimated effort:** 1 session for normalize + audit of medium priority molecules.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Organisms (page-level compositions)
|
||||
|
||||
### Step 3.1 — Normalize all organisms
|
||||
Run `/normalize organisms` for cross-component consistency.
|
||||
|
||||
### Step 3.2 — Full review of critical organisms
|
||||
Organisms are the most complex and user-facing. Run `/audit` + `/critique` +
|
||||
`/harden` on each.
|
||||
|
||||
| Organism | Last Scores | Priority |
|
||||
|----------|------------|----------|
|
||||
| Navigation | — | High (site-wide, visible on every page) |
|
||||
| Footer | Critique 38/40 | Low (excellent score) |
|
||||
| ServiceSelector | — | High (arrangement flow core) |
|
||||
| PackageDetail | Audit 19/20 | Low (excellent score) |
|
||||
| FuneralFinder V1 | Audit 14/20, Critique 29/40 | Medium (pending production decision) |
|
||||
| FuneralFinder V2 | Audit 18/20, Critique 33/40 | Medium (pending production decision) |
|
||||
| FuneralFinder V3 | Audit 18/20, Critique 33/40 | Medium (pending production decision) |
|
||||
|
||||
**Note on FuneralFinder:** All three versions exist. A production decision (v1 vs v2 vs v3)
|
||||
is still pending. Only review the chosen version in depth. The others can be archived or
|
||||
retained as alternatives.
|
||||
|
||||
**Estimated effort:** 1 session for normalize + audit/critique of Navigation + ServiceSelector.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Cross-cutting concerns
|
||||
|
||||
After individual components are clean:
|
||||
1. Run `/adapt` on all organisms + ProviderCard/VenueCard (responsive check)
|
||||
2. Run `/typeset` across a representative sample of each tier
|
||||
3. Run `/preflight` to verify the full codebase
|
||||
4. Commit all fixes
|
||||
|
||||
**Estimated effort:** 0.5 session.
|
||||
|
||||
---
|
||||
|
||||
## Total estimated effort: ~3.5 sessions
|
||||
|
||||
| Phase | Focus | Effort |
|
||||
|-------|-------|--------|
|
||||
| 1 | Atoms normalize + audit | 1 session |
|
||||
| 2 | Molecules normalize + audit | 1 session |
|
||||
| 3 | Organisms normalize + audit/critique/harden | 1 session |
|
||||
| 4 | Cross-cutting (adapt, typeset, preflight) | 0.5 session |
|
||||
|
||||
This can be interleaved with new component work — e.g., review atoms in the
|
||||
morning, build a new molecule in the afternoon. The review findings often
|
||||
improve the patterns used in new components.
|
||||
|
||||
---
|
||||
|
||||
## Decision needed from user
|
||||
|
||||
Before starting, confirm:
|
||||
1. **FuneralFinder version** — Which version (v1/v2/v3) should get the full
|
||||
review? The others can be lightly maintained or archived.
|
||||
2. **Depth vs speed** — Do we fix all P2 issues too, or strictly P0/P1 only?
|
||||
P0/P1 only is faster and doesn't risk changing things that already work.
|
||||
3. **Interleave with new work** — Review in dedicated sessions, or mix with
|
||||
building remaining components (FormField, ArrangementForm, PricingTable)?
|
||||
Reference in New Issue
Block a user