product-design

# Product Design

Decide **what to build and why** before arguing about spacing.

Two rules are non-negotiable:

> **Never design from the surface. Establish what the business actually models
> first.**

> **Never turn the business model into the information architecture. The domain
> constrains what the surface may claim; the user's retrieval and decision task
> determines how the surface is organized.** (`P-14`)

This skill handles product meaning first. It may hand a grounded frame to `ux` or
`design-prototype`, but discovery does not require implementation or a prototype.
Strip out every framework, table and component name: if no product insight remains,
the finding belongs in an engineering skill.

## Relationship to other skills

| Skill                                            | Question                                      | When                        |
| ------------------------------------------------ | --------------------------------------------- | --------------------------- |
| **product-design**                               | What should this surface be, and why?         | Before or during framing    |
| [ux](../ux/SKILL.md)                             | How should the interaction behave and feel?   | While designing or building |
| [ux-audit](../ux-audit/SKILL.md)                 | Does the built surface honor those rules?     | After it exists             |
| [design-prototype](../design-prototype/SKILL.md) | How can a materialized interaction be tested? | When a prototype is useful  |

## Select the smallest run mode

| Mode            | Finish line                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| **Discover**    | Evidence map, business model, user-model hypotheses and structural diagnosis |
| **Frame**       | Discover + view model, information architecture, scope and open decisions    |
| **Materialize** | Frame + a requested spec and/or prototype                                    |

Do not create or modify artifacts unless the user asked for a design artifact,
prototype or repository change.

For a substantial run, read [references/pattern-base.md](references/pattern-base.md)
and [references/layer-model.md](references/layer-model.md) in full. For a narrow
question, inspect only the relevant patterns and state what scope was checked.

## Step 1 — Ground the business model

Establish what is true before diagnosing the surface. For broad repositories,
parallelize independent evidence areas when delegation is available and useful;
the primary agent remains responsible for reconciling contradictions.

Produce:

- Concepts, roles and states, including variants the current surface hides (`P-04`).
- Who produces the terminal business fact and what closes the lifecycle (`P-12`).
- What each state obliges someone to do (`P-01`).
- What business event each action produces (`P-02`).
- Concepts the business does not have (`P-06`).
- Evidence sources, contradictions and confidence.

Treat domain types and state machines as strong evidence, not the sole source of
truth. Check relevant service behavior, permissions, policy, production facts and
user evidence when available. Code can be stale, accidental or incomplete.

Never proceed from the team's assumed model of the product. Treat it as a
hypothesis until checked against domain and user evidence.

## Step 2 — Frame the user's view model

Grounding constrains what the product may claim; it does not determine how a
person should see it. Separate observed user evidence from design hypotheses:

- **Circumstance and job** — “When I open this, I need to …”.
- **Lookup objects** — stable things the user scans, compares or inspects.
- **Attached proof** — what verifies each object without reconstructing joins.
- **First scan** — the 2–4 questions answered without a click.
- **Secondary dimensions** — chronology, provenance, runs and internal states;
  keep them as filters or drill-down unless the job is execution audit.
- **Evidence and confidence** — mark claims as observed, reported or inferred;
  state how consequential assumptions can be validated.

| Model                 | Role in design                                                     |
| --------------------- | ------------------------------------------------------------------ |
| Business/domain model | Defines truth, validity, completeness and red lines                |
| User view model       | Defines grouping, ordering, labels and default expansion           |
| Execution model       | Supplies provenance and audit detail; never gets the page for free |

Do not proceed while proposed top-level sections are merely domain or execution
nouns such as `runs`, `reports`, evidence versions or table names. Rewrite them in
the objects the user is trying to find (`P-14`).

## Step 3 — Diagnose the structural error

Name something wrong regardless of taste, for example:

- A decision inbox exposes only errors, so it reads as an error log (`P-04`).
- A button promises a business event that does not exist (`P-05`).
- One page is both triage desk and reading room, and fails at both (`P-07`).

If no structural error can be supported by evidence, report that instead of
manufacturing a diagnosis.

## Step 4 — Align decisions by dependency

Surface only decisions that change the shape of the answer. For each, give a
recommendation, evidence and consequence. Resolve upstream decisions before the
downstream ones they constrain.

Ask a blocking question separately when its answer would materially change the
work; group independent decisions in one memo. When the user authorizes autonomous
progress, proceed with the recommended default and label the assumption. Never ask
the user for something available through grounding.

For review, approval or acceptance surfaces, establish first whether the system or
a human decision closes the lifecycle (`P-12`).

## Step 5 — Proto