Parsons/docs/reference/component-lifecycle.md

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.