experience-voice

Files (6)

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

SKILL.md (first lines)

# experience-voice

## Purpose

Author the **instance's** verbal experience layer — the two documents that say how this instance's
products are allowed to sound:

- `system/experience/voice_restrictions.md` — the limits.
- `system/experience/voice_direction.md` — what products inherit, and the fallback a run authoring
  one product's words reads when nothing else answers it.

This runs at the **instance** altitude. Nothing it writes says anything about any one product;
where that line sits, and the setup sequence this step belongs to, are
`<CORE>/doctrine/setup/setting_up_an_instance.md`, which owns them.

This file is the **orchestrator**: posture, the file loop, path resolution, the contract, staging,
and the commit. **How to author** — what belongs at this altitude, what evidence an entry needs,
which medium a limit reaches, the markers, when a category is left open, the bar an entry is worded
to, and what goes to the owner instead of being settled — is the authoring prompt
**`prompts/rich.md`**, applied at Step 2; a rule named
below without its content lives there. The documents' **section shape** is the templates
**`<CORE>/templates/experience-templates/voice_restrictions_template.md`** and
**`voice_direction_template.md`**; the companions' shape is **`voice_open_issues_template.md`**
beside them. None of the four is summarised 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 `content-manager` subagent)
as well as in an interactive `content-manager:` session.

**There is no machine gate, which is why this Workflow has four steps where its peer has five.**
`experience-visual` lints `visual_direction.md` against an external format before it commits;
neither document here has a machine-checkable format, so there is no such step and no exit code to
read. What stands in its place is the bar the prompt's § *There is no machine that can check this*
carries — met by how an entry is worded, never by passing anything.

---

## Posture

**Content Manager role required.** If invoked outside Content Manager posture (neither a
`content-manager:` session nor the `content-manager` subagent), stop and say: *"experience-voice
requires Content Manager posture. Switch? (Open a session with the `content-manager:` prefix, or run
the `content-manager` subagent.)"* Do not shed the role.

**The seat's reach over this altitude is the loader's, and this skill grants nothing.**
`<CORE>/roles/loaders/content_manager_global.md` § *What you own*, item 2, gives the Content Manager
the instance's own verbal rules — its writing bar and its verbal experience layer — and says what
makes them this seat's. Read it there.

---

## 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/voice_restrictions.md` | The limits — best-effort complete on every run. | Permanent; one document, revised and versioned in place. |
| `system/experience/voice_direction.md` | What products inherit, plus the fallback section. | Permanent; one document, revised and versioned in place. |
| `system/experience/voice_restrictions_open_issues.md` | The limits document's companion — the calls awaiting the owner and the few things the run could not settle, in the buckets `voice_open_issues_template.md` defines. | Transient. **Its absence is the done signal for that document.** |
| `system/experience/voice_direction_open_issues.md` | The direction document's companion, same shape. | Transient. **Its absence is the done signal for that document.** |
| `system/experience/trail/voice/cycle-<N>.md` | Each answered companion, retired whole. | Permanent. |
| `system/experience/visual_voice_contract.md` | The handoff this run reads and records into — see the section below. | Permanent. **`experience-visual` creates it**, on the first run of the pair; never this skill, whose rows are always added to a file already there. |

**The two documents are tracked separately.** A run can finish the limits 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 a separate gate, and it is not this skill's.

**Cycle numbering:** `N` is one higher than the **highest** `cycle-<N>.md` already in
`trail/voice/` — 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/voice/` 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
   `voice_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 3'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, which this run reads before it writes

`system/experience/visual_voice_contract.md` is **an input to this run, not only a place it leaves
rows.** It carries every fence entry the visual half wrote, with the ones reaching this medium
marked, and those marks are the work list this run starts from. Read it at Step 1, before either
document. Why the marks exist and what the order between the two halves buys is
`<CORE>/doctrine/setup/setting_up_an_instance.md` § The three rules, rule 1 — read there, not here;
what a mark obliges you to *write* is the prompt's § The marks you are reading.

**Neither this skill nor the prompt owns the contract's columns**, and neither restates them: they
are `<CORE>/templates/experience-templates/visual_voice_contract_template.md`'s, and the file on disk
carries them in its own header.

**If the file is not on disk, do not create it and do not guess its shape.** It is
`experience-visual`'s to create, on the first run of the pair — so its absence means step 4a has not
run, or ran without leaving one. The pair has run out of order, and that is a defect to report rather
than a hole to fill. Record in both companions that the handoff is missing and that this run

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp