product-uxd

Files (29)

• README.md
• SKILL.md
• evals.json · evals/
• README.md · evals/inputs/
• agari.md · evals/inputs/mailmate/
• PRD.md · evals/inputs/mailmate/docs/
• product_request.md · evals/inputs/mailmate/docs/
• cycle-1.md · evals/inputs/mailmate/docs/trail/prd/
• project.md · evals/inputs/mailmate/
• agari.md · evals/inputs/trimly-reentry/
• PRD.md · evals/inputs/trimly-reentry/docs/
• UXD.md · evals/inputs/trimly-reentry/docs/
• UXD_open_issues.md · evals/inputs/trimly-reentry/docs/
• product_request.md · evals/inputs/trimly-reentry/docs/
• cycle-1.md · evals/inputs/trimly-reentry/docs/trail/prd/
• project.md · evals/inputs/trimly-reentry/
• agari.md · evals/inputs/trimly/
• PRD.md · evals/inputs/trimly/docs/
• product_request.md · evals/inputs/trimly/docs/
• cycle-1.md · evals/inputs/trimly/docs/trail/prd/
• project.md · evals/inputs/trimly/
• claude.md · intelligence/
• codex.md · intelligence/
• gemini.md · intelligence/
• hf.md · intelligence/
• ollama.md · intelligence/
• launcher.md
• rich.md · prompts/
• stack.json

SKILL.md (first lines)

# product-uxd

## Purpose

Author a project's **UXD** (UX Design Specification): the experience source of truth — the
experience-level **what**, derived from the CPO's PRD. It is written **alongside the CTO's SRS**:
both come off the settled PRD, neither derives from the other, and the SDD needs both. The sequence
is `<CORE>/doctrine/setup/setting_up_a_project.md`, which owns it and is not restated here.

This file is the **orchestrator**: posture, the file loop, path resolution, staging, and the
commit. **How to author** — the UXD-completeness lens, the anti-default discipline, the PRD
critique, the sorting test, the provenance gate, the stability rule, and the tone —
is the authoring prompt **`prompts/rich.md`**, applied at Step 2; a rule
referenced below by name lives there. The UXD's **section shape** is the template
**`<CORE>/templates/product-templates/uxd_template.md`**; the companion's shape is
**`uxd_open_issues_template.md`** beside it. None of them is restated here.

**Non-interactive.** The run never blocks on the owner: it derives the whole UXD best-effort,
writes what it can't settle into a companion open-issues file the owner answers on their own time,
and a re-run folds those answers in. That is what lets it run headless (as the `cdo` subagent) as
well as in an interactive `cdo:` session.

---

## Posture

**CDO role required.** If invoked outside CDO posture (neither a `cdo:` session nor the `cdo`
subagent), stop and say: *"product-uxd requires CDO posture. Switch? (Open a session with the
`cdo:` prefix, or run the `cdo` subagent.)"* Do not shed the role. Where the CDO ends and the
delivery-tier **Architect** begins is a posture fact the CDO loader stack already owns — the two
share the word "design" and nothing else, and the boundary comes from there, never from a
restatement here.

---

## The files and the loop

product-uxd produces the files below under the product's `docs/` — the skill resolves the
locations (next section); a caller names the **project**, never the paths.

| File | What it is | Lifecycle |
|---|---|---|
| `<Product path>/docs/UXD.md` | The UXD — best-effort complete on every run. | Permanent; one document, revised and versioned in place (the bump-on-material-change rule is the template's own header note), never forked. |
| `<Product path>/docs/UXD_open_issues.md` | The companion, holding what the run couldn't settle, in the buckets `uxd_open_issues_template.md` defines — kept distinct, never blurred. Which bucket an item lands in, and how it is led, is the prompt's. | Transient — exists only while something is unresolved. **Its absence is the done signal.** |
| `<Product path>/docs/trail/uxd/cycle-<N>.md` | Each answered companion, retired whole. | Permanent. |

**Cycle numbering:** `N` is one higher than the **highest** `cycle-<N>.md` already in `trail/uxd/` —
list the directory and take the max, so a removed or renamed cycle can't make you collide with an
existing one. The first is `cycle-1.md`; create `trail/uxd/` if it isn't there. Never overwrite an
existing cycle.

**The loop, repeated until clean:**

1. The run derives/updates the UXD and writes the companion with what it couldn't settle.
2. The **owner answers inline** — filling the companion's answer slots, whose names and shape are
   `uxd_open_issues_template.md`'s, stated there and not here — and re-runs the skill.
3. The run **copies the answered companion whole to the next trail cycle**, folds the answers into
   the UXD, and rewrites the companion with only what is still unresolved — an answer the fold
   leaves unsettled still drops, its residue re-raised as a fresh unanswered item. This is the
   ordinary cycle — something survives the fold. A run where nothing would is step 4's, and step 4
   alone says what it may touch.
4. When the answers resolve everything, the run is the close: one run that folds, copies the
   answered companion to the trail, and **removes** the companion instead of rewriting it — through
   the builder, Step 3's `--rm`, never a hand-`rm`. **No open-issues file = the UXD is done.** The
   close has a precondition the ordinary cycle does not: the owner's answers must already be
   committed (Workflow Step 3 owns the rule and why). Re-entry is inline answers, so the first
   closing touch normally finds them uncommitted — and then it **changes nothing at all**: no fold,
   no trail copy, no rewrite, no commit; the companion survives intact, answers and all, for the
   owner to commit. It reports the state and asks for that commit; the re-run after it is the close,
   start to finish, in one run. That stop is a report with an ask, not a live interview.

Step 3 is why the trail exists. Folding rewrites the companion and the close removes it — so
without the trail the owner's answers are destroyed twice, and their reasoning for a decision
survives only in git history. The trail costs one `cp` on the same commit and makes every owner
answer permanently citable. It is the skill's job; the owner never manages it.

---

## Inputs and where the files land

- **The PRD** — your primary input; read it in full, status line included. Its location is
  `product-prd`'s to name — that skill wrote it, and its own file table owns where the PRD lands
  under the product's `docs/`; resolve the path from `<CORE>/../skills/cpo/.claude/skills/product-prd/SKILL.md`, never
  from a path remembered here. It must exist: if nothing is at the resolved path, halt and report —
  there is nothing to derive a UXD from. What the status line means for the derivation — including
  a line that is missing or carries a value the PRD template's vocabulary does not hold — is the
  prompt's rule; whatever it raises reaches the owner through the companion like any other item.
- **`system/projects/<name>/agari.md`** — the project's 上がり Agari, the declared terminus, beside
  the card below. Read it in full. What it means for the derivation is the prompt's rule; it is the
  scope boundary, not a source of experience requirements, and the prompt says how that binds.
  **Its absence does not halt the run** — neither does a file still carrying the placeholder
  `project-stamp` stamps. Agari and UXD gate each other in neither direction
  (`<CORE>/doctrine/setup/setting_up_a_project.md`), so a project may legitimately reach the UXD
  first; the state reaches the owner through the companion, exactly as
  an unreadable PRD status line does.
- **`system/projects/<name>/doctrine/`** — the project's own doctrine, if the folder holds anything.
  Read what is there. An empty or absent folder is silence, not a halt.
- **The product's `docs/` folder** — read it by **listing the directory**, not by recalling a set of
  filenames. Beyond the PRD and the UXD loop files named here, whatever else the folder holds is
  input the run is entitled to: the product request the PRD was derived from, the PRD's own trail of
  owner answers, anything a later round adds. What each carries, and which supersedes which, is the
  prompt's § *Inputs you work from*. Skip binary assets. Enumerating rather than naming is
  deliberate — a list of filenames kept here goes stale the day the product gains a document, and
  the run would never know what it had missed.
- **Context and constraints** — whatever the owner hands you, or the docs it points at. What counts
  as one is the prompt's § *Inputs you work from*; read the list there, it is not restated here.
- **`system/projects/<name>/project.md`** — the directed project's card. Its `Product path:` field
  resolves where every output lands; the field is the card template's
  (`<CORE>/templates/project_template.md`, the shape `project-stamp` stamps the card from), so
  read it from the card in hand. Every later `Product path:` in this file means that field.

**Path resolution.** A relative `Product path:` is inside the instance repo; an absolute one is
outside it, in whatever repo holds the product (which need not be its root — Step 1 resolves that
repo as `<repo>`). Every instance-relative path this file names (`system/…`, `.claude/…`) resolves
from the instance repo root — the directory the session opened in; no step `cd`s away from it. If
`Product path:` is a placeholder or awaits an owner value, halt and report: both outputs resolve
from it, so there is nowhere to write even an open issue recording the gap. Never invent one.

---

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp