---
name: design-reconcile
description: Reconcile an imported claude.ai/design against the web capability ledger before any code — classify every surface as Supported / Cosmetic / Available-unsurfaced / Unsupported, catch watermelon-UI, and produce the PM sign-off report. Use at design-loop leg 3, after a design is approved and before the build.
version: 1.0.0
owner: wawan
risk: medium
category: design
scope: read:okf, read:planning, write:planning/design
---

# design-reconcile — The Design Reconciliation Gate

This skill is the **gate at leg 3** of the [design loop](/okf/core/concepts/design-loop.md): before any
code is written, reconcile the returned claude.ai/design against what the product can actually back. It
realizes the reconciliation rule captured in the product's capability ledger (PMOS's own is
[web-capability-ledger.md](/planning/web-capability-ledger.md)) and is the
[watermelon-flag](/okf/core/concepts/watermelon-flag.md) defense applied to UI — it catches a design that
*looks* functional but has no backend, before it becomes hollow, green-on-the-surface code.

> **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)).
> Level 1 above is the trigger; this body is Level 2.

## Non-negotiable stance

- **Default-to-refute on capability.** For every control the design shows, assume it has **no backend**
  until you find the concrete read/write path in the ledger. A button, field, or toggle is watermelon-UI
  until proven otherwise.
- **Never fake, never silently wire to nothing.** A control with no backing is not "implement later" — it
  is a disposition the PM must rule on now.
- **Presentation-only is the boundary.** A design element that would require new data, a new flow, or
  secrets in the client is **out of scope for the build** and becomes a separate decision
  ([D48](/okf/products/pmos/adr/d48-design-loop.md), [D08](/DECISIONS.md) — the client never holds keys).
- **Advisory to the PM, not self-clearing.** You classify and recommend; the PM signs off the Unsupported
  dispositions ([Acceptance Gate](/okf/core/concepts/output-eval.md), D12). The build does not start until
  they do.

## Procedure

1. **Read the product's capability ledger** — the source of truth for what its app can read (§A), write
   (§B), what data exists but is unsurfaced (§C), and what has no backing (§D). (PMOS's own ledger is
   [web-capability-ledger.md](/planning/web-capability-ledger.md).)
2. **Enumerate every design element.** Walk each surface and list every control, field, table, and badge —
   not just the headline views. Coverage is the point; a missed control is a missed watermelon.
3. **Classify each element** into one of four dispositions:
   - **✅ Supported** — maps to a real read/write (§A/§B) → implement 1:1.
   - **🎨 Cosmetic** — pure presentation on already-loaded data (theme, sort, client filter, expand) → free
     to implement.
   - **🟡 Available-unsurfaced** — data exists (§C) but the design newly surfaces it → opt-in; flag it, wire
     only if the PM wants it.
   - **⛔ Unsupported** — no backend (§D) → do **not** build; record as "design shows X, no backing —
     drop / stub / new-initiative?".
4. **Name every watermelon-UI explicitly.** Call out each control that looks functional with no backend —
   e.g. a Routing screen with provider connections and API-key fields when there is no connections table and
   the client must never hold keys (D08). This is the single highest-value output of the gate.
5. **Produce the reconciliation report** — the four grouped lists, a headline (is the design mostly faithful,
   or does a view over-reach?), and a recommended disposition per Unsupported item.
6. **Hand to the PM.** The Unsupported dispositions are a sign-off; the build starts only once the PM
   confirms them. Each dropped Unsupported item becomes a **capability-honesty** check in the
   [design-fidelity rubric](/planning/evals/design-fidelity-eval-rubric.md) the build is scored against.

## Output and placement

- Reconciliation instances are **operational**. They live under `/planning/design/`, e.g.
  `<slug>-design-reconciliation.md`. ([planning/design-reconciliation.md](/planning/design-reconciliation.md)
  is the first instance.)
- The report feeds two things: the PM Acceptance-Gate sign-off, and the capability-honesty dimension of the
  design-fidelity rubric.

## Level 3 sub-cases

- A design that proposes a genuinely new capability worth its own initiative (not just a drop/stub): see
  `design-reconcile-new-capability.md` (author on first need).