meta-planning-web-planning · git:20260809.786f3c8 · 2026-08-09 · sha256 c6cbf6d32d17f875
meta-planning-web-planning git:20260809.786f3c8A
Immutable. This exact content is served forever at /api/v1/blob/c6cbf6d32d17f875.
---
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.
```markdown
## 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 the container."
```
**Rules the spec must state:**
- Every referenced pattern names a file and line range that was actually read — an unverified reference is a guess
- Why each pattern is the right reference, in one line
- Which utilities and components must be reused rather than re-created (validation helpers, API client wrappers, shared inputs)
---
### Pattern 3: Form Contracts
A form is specified field by field, then as a whole.
| Element | Specify |
| ----------- | --------------------------------------------------------------------------------- |
| Fields | Name, input type, initial value and where it comes from |
| Validation | Rule per field, when it fires (on blur, on submit), exact error message |
| Submission | What is sent, to which endpoint, and the button's disabled-while-pending behavior |
| Success | The message or navigation that confirms the save |
| Failure | Network and server-validation errors — what is shown, what is preserved |
| Dirty state | Whether unsaved changes warn on close/navigation |
```
BAD: "Validate the email"
GOOD: "email: required, format-validated on blur. Invalid: 'Enter a valid email
address' below the field. Submit disabled while pending; server 422 maps
field errors back to the matching inputs, values preserved."
```
---
### Pattern 4: State Ownership
Every piece of state has exactly one named owner.
```markdown
## State Ownership
For EACH piece of state the feature introduces or touches:
- [ ] Owner named: which store, or which component's local state
- [ ] Derived values computed, not stored — if it can be computed from existing state, it is
- [ ] Server data cached through the codebase's existing data-fetching layer, not mirrored into a store
- [ ] Existing store structures unchanged unless the spec explicitly changes them
```
**Why this matters:** state added in the wrong place is the hardest thing to move later. A spec that says "add updateProfile to UserStore, do not restructure it" prevents both the second store and the accidental rewrite.
---
### Pattern 5: Scope Fencing by Directory
Bound the change in file terms, both directions.
```markdown
## Scope Boundaries
**Files to Modify:** [each named file, with what changes in it]
**Files to Create:** [each new file, with its purpose]
**Files NOT to Touch:** [the stores, shared components, and auth surfaces the feature
merely consumes — with why each is off-limits]
```
```
BAD: "Don't break anything"
GOOD: "Do not modify: the authentication flow (auth/), existing stores (stores/),
shared components (components/shared/). Changes are limited to profile/."
```
A verification command belongs with the fence: `git diff -- <excluded paths>` should be empty.
---
### Pattern 6: Measurable UI Success Criteria
Each criterion is a yes/no check with a named verification method.
```
BAD: - Feature works well
- Good user experience
- No bugs
GOOD: 1. Clicking "Edit Profile" opens the modal with current name, email, bio
2. Invalid email shows 'Enter a valid email address'; valid input clears it
3. Save updates the profile and shows the success message within 2 seconds
4. Network failure shows the retry message; entered values are preserved
5. All interactive elements reachable by keyboard; focus returns to the
trigger button on close
6. No changes outside profile/ (git diff -- stores/ components/shared/ is empty)
```
**Rules the spec must state:**
- Each criterion names how it is verified: a test file, a manual check, or a command
- Accessibility criteria are stated for what the feature adds — keyboard reachability, focus behavior, labels
- Performance criteria carry a number when they exist at all ("under 2 seconds", not "fast")
</patterns>
---
<decision_framework>
## Decision Framework
### Which Spec Sections Does This Feature Need?
```
Does the feature render data from an async source?
├─ YES → UI States section (Pattern 1) — all four states
└─ Does it include a form?
├─ YES → Form Contract section (Pattern 3), field by field
└─ Does it introduce or move client state?
├─ YES → State Ownership section (Pattern 4)
└─ NO → Pattern references + scope fence + criteria may be the whole spec
```
Always applicable: Pattern-reference discipline (Pattern 2), Scope fencing (Pattern 5), Measurable criteria (Pattern 6).
### Common Spec Failures
| Failure | Consequence |
| -------------------------------------- | ------------------------------------------------------------- |
| Only the success state specified | Loading, error, and empty ship as blank or broken screens |
| "Use proper form handling" | Each form invents its own validation timing and error display |
| No do-not-touch list | The feature "fixes" a store and breaks its other consumers |
| Criteria like "works well" | Nothing gates the merge; review becomes opinion |
| Server data mirrored into a store | Two sources of truth; stale UI after every mutation |
| Pattern reference without line numbers | The reference was never verified to exist |
</decision_framework>
---
<red_flags>
## RED FLAGS
**High Priority Issues (a spec with one of these is incomplete):**
- A data-driven surface with no loading, error, or empty behavior specified
- A form without per-field validation rules and messages
- No do-not-touch list on a feature that consumes shared stores or components
- Success criteria that cannot be answered yes/no
**Medium Priority Issues:**
- A new component where the referenced codebase pattern already provides one
- State introduced without a named owner
- Accessibility unmentioned on new interactive elements
- A pattern reference to a file that was never read
**Common Mistakes:**
- Specifying the modal's content but not its close/cancel/focus behavior
- Leaving "what happens to entered values on failure" undecided
- Writing enhancement wishes into the must-have list
- Describing visual design the design system already decides
**Gotchas & Edge Cases:**
- Empty and error states can coincide (failed load of an empty list) — decide which wins
- A disabled submit button needs a reason the user can see
- Optimistic updates need a rollback story in the spec, or must be explicitly out of scope
</red_flags>
---
<critical_reminders>
## CRITICAL REMINDERS
> **All specifications must be grounded in the codebase's real components, stores, and form patterns**
**(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)**
**Failure to specify these contracts produces UIs whose error and empty states are accidents, whose forms each validate differently, and whose "done" nobody can verify.**
</critical_reminders>