Fix /define-design missing screens: exhaustive screen inventory before design

/define-design now builds docs/design/screen-inventory.md first — derived
from every PRD user story walked end-to-end, CRUD coverage per entity
(list/detail/create/edit/delete, modals included), and supporting screens —
then requires one blueprint entry per inventory item, checked off as added.
Consistency check verifies inventory coverage and end-to-end story
completability. /update-design keeps the inventory in sync; ui-design
skill documents the inventory rules.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.opencode/command/define-design.md

@@ -62,7 +62,7 @@ Ask the user about the following. If the user does not provide detailed preferen
 
 - **Target platform**: `web`, `flutter`, `winui3`, or `multi`
 - **Visual style** (e.g. friendly/modern/rounded/calm, dark or light, density)
-- **Main screens** the app must have
+- **Main screens** the app must have (treat the answer as additions and constraints — the complete screen list is derived from the PRD in Step 3, never limited to what the user names here)
 - **Navigation style** (e.g. tab bar, drawer, sidebar, stack)
 - **Branding preferences** (name, colors, tone)
 - **Accessibility requirements** (e.g. WCAG level, minimum contrast, large-touch targets)
@@ -74,7 +74,30 @@ Collect the answers in a single round; do not pause again until generation is co
 - Follow the **ui-design** skill (loaded automatically) to create `design-brief.md`, `ui-blueprint.json`, and the SVG wireframes.
 - Follow the **design-tokens** skill (loaded automatically) to create `design-tokens.json`.
 
-### Step 3: Create the Design Brief
+### Step 3: Build the Screen Inventory (exhaustive — before designing anything)
+
+The most common design failure is a missing screen — e.g. a todo app with a list screen but no screen for adding a new item. To prevent it, enumerate **every** screen the requirements imply and write the list to `docs/design/screen-inventory.md` **before** creating any other design file.
+
+Derive the inventory from the documents read in Step 0. The user's Step 1 answer about main screens is input, never the ceiling.
+
+1. **Walk every user story and requirement** in `docs/product-requirements.md`, and every flow in `docs/functional-design.md`. For each one, write down every screen the user passes through to complete it end-to-end. If a story cannot be completed with the screens listed so far, the missing screens go on the list.
+2. **Apply CRUD coverage to every entity** the user manages (e.g. todo item, project, profile). For each entity, explicitly decide each of: list/overview, detail, **create/add**, edit, delete confirmation. Include each as an inventory entry unless the requirements clearly exclude it. If create/edit happens in a modal, dialog, or inline form rather than a full page, it is **still an inventory entry** (record its presentation) — it still needs a blueprint entry and a wireframe.
+3. **Add the supporting screens** the requirements imply: authentication (sign in / sign up / password reset), settings, onboarding, search/filter results, empty states, error / not-found.
+
+Write each entry in this format:
+
+```markdown
+- [ ] `screen-id` — Title
+  - Purpose: what the user accomplishes here
+  - Source: the PRD user story / functional-design section it comes from
+  - Reached from: the screens/actions that navigate here
+  - Presentation: page | modal | drawer
+  - Key elements: main components, inputs, and actions on the screen
+```
+
+End the file with a **traceability table**: one row per user story, listing the screen ids that fulfill it. Every user story must map to at least one screen, and every screen must trace back to at least one requirement. Do not proceed to Step 4 until both directions are fully covered.
+
+### Step 4: Create the Design Brief
 
 Create `docs/design/design-brief.md` covering:
 
@@ -88,7 +111,7 @@ Create `docs/design/design-brief.md` covering:
 - Examples of preferred UI style
 - Examples of UI style to avoid
 
-### Step 4: Create the Design Tokens
+### Step 5: Create the Design Tokens
 
 Create `docs/design/design-tokens.json` using a JSON structure inspired by the Design Tokens Community Group format (each token has `$type` and `$value`). Include:
 
@@ -100,7 +123,7 @@ Create `docs/design/design-tokens.json` using a JSON structure inspired by the D
 - Animation durations / easings
 - Breakpoints (if the target includes web)
 
-### Step 5: Create the UI Blueprint (source of truth)
+### Step 6: Create the UI Blueprint (source of truth)
 
 Create `docs/design/ui-blueprint.json`. This is **the** source of truth for UI generation. It must describe:
 
@@ -113,7 +136,9 @@ Create `docs/design/ui-blueprint.json`. This is **the** source of truth for UI g
 - Component hierarchy
 - User actions and navigation behavior
 
-### Step 6: Create the Platform Mapping
+**Coverage rule**: the blueprint must contain one screen entry for **every** entry in `docs/design/screen-inventory.md` — including modal/drawer entries. As each screen is added, check it off (`[ ]` → `[x]`) in the inventory. Do not finish this step while any inventory entry is unchecked.
+
+### Step 7: Create the Platform Mapping
 
 Create `docs/design/platform-mapping.md` describing how the design spec is converted to each platform:
 
@@ -131,7 +156,7 @@ WinUI 3:
 - ui-blueprint.json → XAML pages, UserControls, styles
 ```
 
-### Step 7: Generate SVG Wireframes (visual references only)
+### Step 8: Generate SVG Wireframes (visual references only)
 
 For each screen in `ui-blueprint.json`, generate a corresponding SVG wireframe under `docs/design/screens/`:
 
@@ -141,10 +166,12 @@ For each screen in `ui-blueprint.json`, generate a corresponding SVG wireframe u
 
 **Important rule**: SVG files are **not** the source of truth. They are generated as visual references for human review only. The source of truth is `ui-blueprint.json`. If the blueprint and an SVG ever disagree, the blueprint wins and the SVG must be regenerated.
 
-### Step 8: Consistency Check
+### Step 9: Consistency Check
 
 Re-read all generated files and confirm:
 
+- Every entry in `docs/design/screen-inventory.md` is checked off and has a matching screen (same id) in `ui-blueprint.json`.
+- Every user story in the PRD can be completed end-to-end using only the screens and actions in the blueprint — in particular, every entity the user can create, edit, or delete has a screen (or modal) for each of those operations.
 - Every screen in `ui-blueprint.json` has a matching SVG in `screens/`.
 - Token names referenced in `ui-blueprint.json` exist in `design-tokens.json`.
 - `platform-mapping.md` covers all target platforms selected in Step 1.
@@ -154,6 +181,7 @@ Fix any inconsistencies found before finishing.
 
 ## Completion Criteria
 
+- `docs/design/screen-inventory.md` exists and every entry is checked off
 - `docs/design/design-brief.md` exists
 - `docs/design/design-tokens.json` exists and is valid JSON
 - `docs/design/ui-blueprint.json` exists and is valid JSON
@@ -165,6 +193,7 @@ Completion message:
 "Design phase is complete!
 
 Design documents created:
+✅ docs/design/screen-inventory.md  (exhaustive screen list — all entries covered)
 ✅ docs/design/design-brief.md
 ✅ docs/design/design-tokens.json
 ✅ docs/design/ui-blueprint.json   (source of truth)

.opencode/command/update-design.md

@@ -39,6 +39,8 @@ Read:
 
 The blueprint is the source of truth, so it is always updated first. Add/modify screens, components, variants, states, routes, and actions to reflect the requested change. Keep the JSON valid and consistent with the existing schema.
 
+If the change adds or removes screens, also update `docs/design/screen-inventory.md` (create it if missing — see the ui-design skill) so it stays the complete screen list: new screens get a checked (`[x]`) entry with purpose, source, and how they are reached; removed screens are deleted from it.
+
 ### Step 2: Update `design-tokens.json` (if needed)
 
 If the change introduces new colors, spacing, typography, radius, shadows, or animations, add the corresponding tokens here. Reuse existing tokens where possible; do not duplicate. Use semantic names. No hard-coded values should be needed downstream.
@@ -58,6 +60,7 @@ For every screen added or modified in `ui-blueprint.json`, generate or regenerat
 ### Step 6: Consistency Check
 
 - Every screen in `ui-blueprint.json` has a matching SVG.
+- `docs/design/screen-inventory.md` (if present) lists exactly the blueprint's screens.
 - Token names referenced in the blueprint exist in `design-tokens.json`.
 - The brief and mapping remain consistent with the blueprint.
 

.opencode/skills/ui-design/SKILL.md

@@ -15,11 +15,12 @@ Prefer describing **what a component is and how it behaves** over describing **w
 
 ## Outputs
 
-This skill produces three kinds of artifacts under `docs/design/`:
+This skill produces four kinds of artifacts under `docs/design/`:
 
-1. `design-brief.md` — the UI/UX direction (human-readable, but concrete)
+1. `screen-inventory.md` — an exhaustive checklist of every screen the requirements imply (always created first)
-2. `ui-blueprint.json` — the source of truth for UI generation (machine-readable)
+2. `design-brief.md` — the UI/UX direction (human-readable, but concrete)
-3. `screens/*.svg` — visual wireframes for human review (derived from the blueprint)
+3. `ui-blueprint.json` — the source of truth for UI generation (machine-readable)
+4. `screens/*.svg` — visual wireframes for human review (derived from the blueprint)
 
 ## Prerequisites
 
@@ -31,6 +32,18 @@ Before creating the design, read:
 
 The design must serve the product requirements and stay consistent with the functional design.
 
+## Creating `screen-inventory.md` (always first)
+
+Never design screens from memory of the requirements — a screen that is not on a written list will be forgotten (the classic miss: a list screen exists but the create/add screen does not). Build the inventory before the brief or the blueprint:
+
+1. **Walk every user story** in the PRD and every flow in the functional design; list every screen the user needs to complete it end-to-end. If a story cannot be completed with the screens listed so far, the missing screens go on the list.
+2. **Apply CRUD coverage per entity**: for each domain object the user manages, explicitly decide list/overview, detail, **create/add**, edit, and delete confirmation — include each unless the requirements clearly exclude it. Modal/dialog/inline forms count as inventory entries too (record the presentation); they still need blueprint entries and wireframes.
+3. **Add supporting screens**: authentication, settings, onboarding, search results, empty states, error / not-found — wherever the requirements imply them.
+
+Each entry is a checkbox item with `screen-id`, title, purpose, source requirement, how it is reached, presentation (page / modal / drawer), and key elements. End the file with a traceability table mapping every user story to the screen ids that fulfill it — both directions must be covered (no story without screens, no screen without a source).
+
+Check entries off (`[x]`) as their screens are added to `ui-blueprint.json`. The blueprint is not complete while any entry is unchecked.
+
 ## Creating `design-brief.md`
 
 A concrete, opinionated document. Avoid vague phrases like "modern and clean" without elaboration. Include every section below:
@@ -149,6 +162,8 @@ Each node has:
 
 Before finishing:
 
+- [ ] Every entry in `screen-inventory.md` is checked off and exists in the blueprint (same id).
+- [ ] Every user story can be completed end-to-end using only blueprint screens and actions — every entity that can be created, edited, or deleted has a screen or modal for each operation.
 - [ ] Every screen in the blueprint has a matching SVG.
 - [ ] Every `variant` used in a screen is declared in `components`.
 - [ ] Every token name used in the blueprint exists in `design-tokens.json`.

AGENTS.md

@@ -79,6 +79,7 @@ Define "what to build" and "how to build it" for the entire application:
 - **glossary.md** - Ubiquitous language definitions
 
 #### Design Documents (`docs/design/`)
+- **screen-inventory.md** - Exhaustive screen checklist derived from the PRD (coverage guarantee for the blueprint)
 - **design-brief.md** - UI/UX direction
 - **design-tokens.json** - Styling tokens (source of values)
 - **ui-blueprint.json** - UI structure (source of truth for UI generation)

README.md

@@ -27,10 +27,13 @@ PRD, functional design, architecture, repository structure, development guidelin
 (all under `docs/`). Review them and request edits in normal conversation if needed.
 
 ### Step 3 — Define the UI/UX design: `/define-design`
-Creates the design specification under `docs/design/`: design brief, design tokens,
+First builds an **exhaustive screen inventory** (`screen-inventory.md`) from the PRD and
-**`ui-blueprint.json` (the source of truth for UI generation)**, platform mapping, and SVG
+functional design — every user story walked end-to-end, plus list/detail/create/edit/delete
-wireframes (visual references only). You'll be asked once about platform, style, screens,
+coverage for every entity — so no screen gets skipped. Then creates the design specification
-navigation, branding, and accessibility.
+under `docs/design/`: design brief, design tokens, **`ui-blueprint.json` (the source of truth
+for UI generation, one entry per inventory screen)**, platform mapping, and SVG wireframes
+(visual references only). You'll be asked once about platform, style, screens, navigation,
+branding, and accessibility.
 
 ### Step 4 — Review and refine the design **before writing any code**
 This is the key design-decision gate: iterate on the design while it is still cheap to change.
@@ -205,6 +208,7 @@ opencode
 │   ├── ideas/
 │   │   └── initial-requirements.md   # Brainstorming notes (pre-PRD)
 │   ├── design/                # UI/UX design spec (created by /define-design)
+│   │   ├── screen-inventory.md       # exhaustive screen checklist (from the PRD)
 │   │   ├── design-brief.md
 │   │   ├── design-tokens.json
 │   │   ├── ui-blueprint.json         # source of truth for UI
@@ -324,9 +328,12 @@ first if you have your own idea, or replace it.
 > /define-design
 ```
 
-Creates the design specification under `docs/design/` (design brief, design tokens, UI blueprint,
+First builds an exhaustive screen inventory (`screen-inventory.md`) from the PRD and functional
-platform mapping, and SVG wireframes). You'll be asked about target platform, visual style, main
+design — every user story walked end-to-end, with list/detail/create/edit/delete coverage per
-screens, navigation, branding, and accessibility; if you don't specify, sensible defaults are proposed.
+entity — then creates the design specification under `docs/design/` (design brief, design tokens,
+UI blueprint with one entry per inventory screen, platform mapping, and SVG wireframes). You'll be
+asked about target platform, visual style, main screens, navigation, branding, and accessibility;
+if you don't specify, sensible defaults are proposed.
 
 Review and refine the UI/UX **before** generating the app — it is far easier to iterate on the design
 than on generated code:
@@ -504,7 +511,7 @@ Playwright covers the `web` target; for `flutter` the equivalent is `integration
 | `repository-structure` | Defining the directory layout | `docs/repository-structure.md` |
 | `development-guidelines` | Creating coding conventions / implementing code | `docs/development-guidelines.md` |
 | `glossary-creation` | Creating a project glossary | `docs/glossary.md` |
-| `ui-design` | Creating the design brief, UI blueprint, and SVG wireframes | `docs/design/` files |
+| `ui-design` | Creating the screen inventory, design brief, UI blueprint, and SVG wireframes | `docs/design/` files |
 | `design-tokens` | Creating and maintaining design tokens | `docs/design/design-tokens.json` |
 | `platform-ui-generation` | Converting design files into Web/Flutter/WinUI 3 code | generated app code |
 | `milestone-planning` | Planning phases/milestones and the feature breakdown per milestone | `docs/milestones/` phase files |