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>

.claude/skills/build-atom/SKILL.md

@@ -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

.claude/skills/build-molecule/SKILL.md

@@ -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

.claude/skills/build-organism/SKILL.md

@@ -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

CLAUDE.md

@@ -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
 

docs/reference/component-lifecycle.md

@@ -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.

docs/reference/retroactive-review-plan.md

@@ -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)?