experience-visual

Files (6)

• SKILL.md
• claude.md · intelligence/
• codex.md · intelligence/
• ollama.md · intelligence/
• launcher.md
• rich.md · prompts/

SKILL.md (first lines)

# experience-visual

## Purpose

Author the **instance's** visual experience layer — the two documents that say what this instance's
products may and may not look like:

- `system/experience/visual_restrictions.md` — the fence.
- `system/experience/visual_direction.md` — what products inherit, and what a design run falls back
  on when nothing covers its case.

This runs at the **instance** altitude. Nothing it writes says anything about any one product; the
first document that could only belong to a product is that product's own. Where that line sits, and
the sequence this step belongs to, are `<CORE>/doctrine/setup/setting_up_an_instance.md`, which owns
them and is not restated here.

This file is the **orchestrator**: posture, the file loop, path resolution, the contract, the
machine-gate step, staging, and the commit. **How to author** — the altitude test, what evidence an entry needs, the
markers, when a value is left absent, the machine gate's bar, and what goes to the owner instead of
being settled — is the authoring prompt **`prompts/rich.md`**,
applied at Step 2; a rule referenced below by name lives there. The documents' **section shape** is
the templates **`<CORE>/templates/experience-templates/visual_restrictions_template.md`** and
**`visual_direction_template.md`**; the companions' shape is **`visual_open_issues_template.md`**
and the contract's is **`visual_voice_contract_template.md`**, both beside them. None of them is
restated here.

**Non-interactive.** The run never blocks on the owner. It authors both documents best-effort,
writes its load-bearing calls into companion files the owner signs off 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: *"experience-visual requires CDO posture. Switch? (Open a session with the
`cdo:` prefix, or run the `cdo` subagent.)"* Do not shed the role.

The CDO loader stack owns where the CDO ends and the delivery-tier **Architect** begins; that
boundary comes from there, never from a restatement here. One thing this skill does add, because no
loader states it: the CDO's usual subject is one product, and here it is the instance every product
sits under. Same seat, one altitude up.

---

## The files and the loop

Everything lands under `system/experience/` in the instance repo. A caller names nothing — there is
one instance, and this skill is running in it.

| File | What it is | Lifecycle |
|---|---|---|
| `system/experience/visual_restrictions.md` | The fence — best-effort complete on every run. | Permanent; one document, revised and versioned in place. |
| `system/experience/visual_direction.md` | What products inherit, plus the direction section a design run falls back on. | Permanent; one document, revised and versioned in place. |
| `system/experience/visual_restrictions_open_issues.md` | The fence's companion — the calls awaiting the owner and the few things the run could not settle, in the buckets `visual_open_issues_template.md` defines. | Transient. **Its absence is the done signal for that document.** |
| `system/experience/visual_direction_open_issues.md` | The direction document's companion, same shape. | Transient. **Its absence is the done signal for that document.** |
| `system/experience/trail/visual/cycle-<N>.md` | Each answered companion, retired whole. | Permanent. |
| `system/experience/visual_voice_contract.md` | The handoff. **This run creates it** if it is not there, records a row for every fence entry it writes, and marks the ones reaching the verbal medium; `experience-voice` reads those marks and records its own rows back. | Permanent, and never removed — a handoff's absence is a defect, not a done signal. See the section below. |

**The two documents are tracked separately.** A run can finish the fence and still be open on the
direction document, so each companion's absence answers for its own document only. What answers for
the whole layer is `<CORE>/tools/experience_gate.py`, which is not this skill's to run or to satisfy.

**Cycle numbering:** `N` is one higher than the **highest** `cycle-<N>.md` already in
`trail/visual/` — list the directory and take the max, so a removed or renamed cycle cannot make you
collide with an existing one. The first is `cycle-1.md`; create `trail/visual/` if it isn't there.
Never overwrite an existing cycle. Where both companions are answered in one round, each is copied
to its own cycle file.

**The loop, repeated until clean:**

1. The run authors or updates both documents and writes each companion with what it could not
   ground.
2. The **owner answers inline** — filling the companion's answer slots, whose names and shape are
   `visual_open_issues_template.md`'s — and re-runs the skill.
3. The run **copies each answered companion whole to the next trail cycle**, folds the answers into
   its document, and rewrites the companion with only what is still unresolved. An answer that
   leaves something unsettled still drops its item, and the residue re-enters as a fresh unanswered
   item.
4. When the answers resolve everything in a companion, that companion is **removed** rather than
   rewritten — through the builder, Step 4's `--rm`, never a hand-`rm`. **No open-issues file = that
   document is done.** The close has a precondition the ordinary cycle does not: the owner's answers
   must already be committed, because git will not remove a file with uncommitted edits in it and
   their words are not yours to commit. 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. It reports the state, asks for that commit, and the re-run after it is the
   close. 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 survives only in git history.
The trail costs one `cp` on the same commit and makes every owner answer permanently citable. It is
this skill's job; the owner never manages it.

---

## The contract this run records into — and creates, if it is not there

`system/experience/visual_voice_contract.md` is the handoff to `experience-voice`, and **this skill
creates it.** Nothing upstream stamps it: on the first run of the pair the file does not exist, and a
run that leaves none hands the second half no marks at all — the state rule 1 exists to prevent. So
if it is absent, create it from
**`<CORE>/templates/experience-templates/visual_voice_contract_template.md`**, header and all,
before recording anything. If it is present, leave its header alone and add to it.

**Every entry this run writes into `visual_restrictions.md` gets a row** — not only the ones that
reach the verbal medium. Why it is exhaustive, and what a **handoff** is as opposed to a companion,
are the prompt's and `<CORE>/doctrine/setup/setting_up_an_instance.md` § The three rules'; read them
there.

**`visual_direction.md` states no entries in that sense, and this run records none for it.** Its
values carry no slug and no reach, so there is nothing to key a row on and nothing to mark — and
where a direction value looks as though it would bind the verbal medium, what to do with it is rule
2's, at the file named above. Read it there; this skill neither restates it nor improvises around
it.

**Mark every entry that reaches the verbal medium.** The mark *is* the row's **Mediums** cell naming
that medium, taken from the entry's own **Reaches** field rather than judged a second time here — and
those marks are the whole of what `experience-voice` starts from. An entry reaching both mediums and

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp