Govkit Ui Spec Planning

---
name: govkit-ui-spec-planning
description: Generate a UI feature plan (plan.md) and eval_criteria.yaml from NFRs, acceptance scenarios, and architecture preflight. Use when the user asks to plan a UI feature or invokes /govkit-ui-spec-planning.
---

# Spec Planning — UI

You are performing Spec Planning for a UI feature. Determine the feature name from the user's request; if it is not provided, ask before proceeding.

Read the following before proceeding:

- `features/<feature_name>/acceptance.feature`
- `features/<feature_name>/nfrs.md`
- `features/<feature_name>/architecture_preflight.md`
- `features/<feature_name>/design.md`
- `docs/ui/architecture/MVVM_CONTRACT.md`
- `docs/ui/architecture/nextjs/` for `ui-nextjs`
- `docs/ui/design/BRAND.md`
- `docs/ui/evaluation/eval_criteria.md`
- `governance/ui/templates/plan.md`
- `governance/ui/schemas/eval_criteria.schema.json`

---

Produce or update `features/<feature_name>/plan.md` and `features/<feature_name>/eval_criteria.yaml`.

## Behavior contract (skip unless this project has one)

Read `authority` in `.govkit/skill_context.yaml` before anything else. If
`source` is `none` — the default, and where most projects are — **skip this
section entirely**: nothing in it applies, and you should not mention it.

If `source` is `pdg`, this feature's behavior is a **versioned commitment**.
An approved baseline binds its Rules and scenarios to an exact revision, and
what somebody approved is that revision — not the working tree in front of
you, and not your reading of it. The governing rule is the one govkit
installed as `behavior-contract`; it is already loaded, and it is binding.

Before relying on anything in the feature folder:

- Run the `validate-baseline` and `verify-authority` checks exactly as that
  rule specifies them. Both need `--target` and `--baseline`, and
  `verify-authority` also needs `--commitment` — omit it and the answer is
  *not authorized* about the pointer you did not supply, which says nothing
  about your work.
- **Check `sources` in the baseline first.** More than one entry means the
  contract spans repositories and every one of them needs its own
  `--source <source_key>=<path>` checkout. Without them you get refusals
  about missing sources, which are not a verdict on the contract.
- **Drift means stop.** The spec in front of you is not the one that was
  approved, and everything you plan from it inherits that.
- **Unverified is not permission.** An unreachable graph, or an unset
  `GOVKIT_PDG_URL`, leaves the question unanswered rather than answered yes.

Then change nothing that is committed. A scope change, an exclusion you
inferred, a behavior nobody asked for, or a relaxed threshold is a decision
for a person: name the scenario in conflict and wait. You may still refactor,
and this plan may still evolve, as long as every committed scenario keeps
passing.

## plan.md must include:

### 1. Feature Summary
One paragraph describing the feature from the user's perspective.

### 1.5 Scope Boundaries
Populate the plan's `### Out of scope` from `nfrs.md` `## Out of scope`:
- If `nfrs.md` has a non-empty `## Out of scope` section, copy its entries into the plan verbatim (author-declared — no marker).
- If `## Out of scope` is missing or empty, infer the deferred capabilities from the spec's negative space, then BOTH:
  - insert `<!-- INFERRED: not declared in nfrs.md ## Out of scope; confirm with feature owner -->` directly under the plan's `### Out of scope` heading, and
  - state in the planning summary that Out-of-scope was inferred and should be confirmed.

### 2. Architecture Breakdown
For React/Vite and Angular, cover each MVVM layer:
- Components to create (with props interface summary)
- Hooks / query inject functions to create (query keys, data shape, transform)
- Client state additions (Zustand store / Signal store)
- API functions to create (endpoint, method, request/response types)

For `ui-nextjs`, instead cover:
- App Router routes, layouts, loading/error boundaries, and Server Components
- Application use cases and view-model shaping
- Typed backend API adapters
- Feature components and justified Client Components
- Shared primitives/infrastructure
- Cache and freshness behavior

No plan may include direct SQL, database dependencies, ORMs, migrations,
connection strings, or business logic in a Next.js BFF. A missing endpoint is
a backend contract blocker.

### 3. Increment Breakdown
Ordered list of implementation increments. Each increment must be independently testable and deployable.

### 4. Backend Contract Dependencies
List any backend endpoints this feature depends on. Flag any that are not yet available.

### 5. Accessibility Plan
For each Gherkin scenario tagged `@accessibility`: describe the WCAG criteria and test approach.

### 5.5 Visual Direction

Map the approved brand and feature `design.md` to semantic tokens, component
states, responsive behavior, and accessibility. List every screenshot,
mockup, and prototype reference with what may be learned from it. References
remain advisory unless `design.md` promotes a named property to a
requirement. Prototype code (for example an AI-generated HTML prototype in
`design/references/`) is never imported, copied, or extended in `src/` —
promoted behavior enters the plan through `design.md`.

### 6. Evaluation Compliance Summary

```yaml
evaluation_prediction:
  first:
    fast:           { score: 0-5, evidence: "..." }
    isolated:       { score: 0-5, evidence: "..." }
    repeatable:     { score: 0-5, evidence: "..." }
    self_verifying: { score: 0-5, evidence: "..." }
    timely:         { score: 0-5, evidence: "..." }
    average: 0.0
  virtues:
    working:   { score: 0-5, evidence: "..." }
    unique:    { score: 0-5, evidence: "..." }
    simple:    { score: 0-5, evidence: "..." }
    clear:     { score: 0-5, evidence: "..." }
    easy:      { score: 0-5, evidence: "..." }
    developed: { score: 0-5, evidence: "..." }
    brief:     { score: 0-5, evidence: "..." }
    average: 0.0
  accessibility:
    predicted_axe_violations: 0
    wcag_level: AA
  thresholds_met: true|false
```

Scoring rubrics: `docs/ui/evaluation/FIRST_SCORING_RUBRIC.md` and `docs/ui/evaluation/VIRTUE_SCORING_RUBRIC.md`

Do not proceed to Implementation Planning if `thresholds_met` is false, predicted FIRST average is below 4.0, or predicted Virtue average is below 4.0.