/meta-planning-web-planning

name: meta-planning-web-planning
description: Frontend specification planning frameworks. Use when a spec touches UI components, forms, client state, or user-facing flows. Covers UI-state completeness (loading, error, empty, success), component boundaries, form validation contracts, state ownership, and measurable UI success criteria.

Web Planning Frameworks

> **Quick Guide:** Specify every state the UI can be in — loading, error, empty, and success are four different screens, and an unspecified one ships as a blank div. Reference the concrete component and form patterns the implementation must follow (file:line), bound the change to named directories, and write success criteria a reviewer can check with a yes/no: which element appears, what the validation rejects, what the user sees on a network error.

---

<critical_requirements>

CRITICAL: Before Specifying Frontend Work

> **All specifications must be grounded in the codebase's real components, stores, and form patterns** — reference specific files with line numbers

**(You MUST specify every UI state the feature can render — loading, error, empty, and success — or explicitly rule one out)**

**(You MUST reference the concrete component, form, and store patterns to follow, with file and line numbers)**

**(You MUST specify validation per field — the rule, when it fires, and the exact message shown)**

**(You MUST bound the change to named files and directories, with an explicit do-not-touch list)**

**(You MUST write success criteria as yes/no checks a reviewer can verify — never "works well" or "good UX")**

</critical_requirements>

---

**Auto-detection:** UI spec, component spec, frontend feature spec, form spec, modal spec, loading state, empty state, error state, client state design, frontend success criteria

**When to use:**

• Specifying new or changed UI components, pages, or flows
• Specifying forms: fields, validation rules, submission behavior, error display
• Specifying where client state lives and which store owns it
• Specifying loading, error, empty, and success behavior
• Defining measurable success criteria for user-facing work

**When NOT to use:**

• When implementing components (use the relevant web implementation skill)
• For the API the UI calls (use the api planning skill)
• For the planning PROCESS itself — research, scope fencing, success criteria structure — which the PM agent carries

**Key patterns covered:**

• UI-state completeness (loading, error, empty, success)
• Pattern-reference discipline for components, forms, and stores
• Form contracts: fields, validation, submission, feedback
• State ownership and reuse boundaries
• Scope fencing by directory
• Measurable UI success criteria

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Spec fragments and a worked example specification

---

<philosophy>

Philosophy

**A UI spec is a contract about what the user sees, in every state.** The happy path is the easy fifth of the work; the loading spinner, the validation message, the empty list, and the failed request are where an unspecified feature quietly becomes four different developers' four different guesses.

**When specifying frontend work:**

• Find the closest existing component, form, and modal first — their patterns are the spec's vocabulary, referenced by file:line
• Walk the feature through all four states — loading, error, empty, success — and write down what each renders
• Specify validation as the user experiences it: the rule, when it fires, and the exact message
• Name what must NOT change: the stores, shared components, and auth surfaces the feature merely touches

**When NOT to specify:**

• Don't specify implementation details (hook wiring, memoization) — behavior and patterns, not code
• Don't design new UI primitives when the codebase's component library covers the need
• Don't specify visual design beyond what the existing design system already decides
• Don't add "should have" enhancements to the must-have list — scope creep starts in the spec

**Core principles:**

• **Four states or an explicit ruling-out**: an unhandled state ships as a blank screen
• **Patterns by reference, not description**: "follow SettingsForm.tsx:45-89" beats "use proper form handling"
• **State has one owner**: name the store or component that holds each piece; duplicated state is a spec defect
• **Criteria are yes/no**: "invalid email shows an error message" is checkable; "validation works" is not

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: UI-State Completeness

Every data-driven surface has four states. Specify each, or explicitly rule it out.

## UI States

For EACH data-driven surface the spec adds or changes:

- [ ] Loading — what renders while data is in flight (skeleton, spinner, disabled control)
- [ ] Error — what the user sees on failure, and whether retry is offered
- [ ] Empty — what renders with zero items, and whether a call-to-action belongs there
- [ ] Success — the populated state, including singular/plural and overflow behavior

BAD:  "Show the user's projects"
GOOD: "Loading: 3 skeleton rows. Error: inline message with Retry button.
       Empty: 'No projects yet' with a Create button. Success: project cards,
       newest first, 20 per page."

**Why this matters:** the unspecified states are the ones users hit at the worst moments — slow networks and failures. A spec that covers only success delegates the other three to chance.

---

Pattern 2: Pattern-Reference Discipline

Reference the concrete implementation to follow, never a style in the abstract.

BAD:  "Use proper form handling"
GOOD: "Follow the form pattern from SettingsForm.tsx:45-89. Use the same validation
       approach, error display, and success messaging."

BAD:  "Open it in our usual modal"
GOOD: "Use the ModalContainer pattern from components/modals/UpdateAllProjects.tsx:12-78 —
       overlay, positioning, and onClose handled by