diff --git a/.claude/skills/build-atom/SKILL.md b/.claude/skills/build-atom/SKILL.md index 9b0c15d..02bd10b 100644 --- a/.claude/skills/build-atom/SKILL.md +++ b/.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 diff --git a/.claude/skills/build-molecule/SKILL.md b/.claude/skills/build-molecule/SKILL.md index 6aff9f0..76be77d 100644 --- a/.claude/skills/build-molecule/SKILL.md +++ b/.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 diff --git a/.claude/skills/build-organism/SKILL.md b/.claude/skills/build-organism/SKILL.md index fe94bcc..e950a41 100644 --- a/.claude/skills/build-organism/SKILL.md +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index c2e2c30..d041716 100644 --- a/CLAUDE.md +++ b/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 diff --git a/docs/reference/component-lifecycle.md b/docs/reference/component-lifecycle.md new file mode 100644 index 0000000..deba171 --- /dev/null +++ b/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. diff --git a/docs/reference/retroactive-review-plan.md b/docs/reference/retroactive-review-plan.md new file mode 100644 index 0000000..f58f2e0 --- /dev/null +++ b/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)?