User-facing surfaces put a vocabulary to the user without naming it #247

New issue

Closed

opened 2026-08-23 20:43:32 +00:00 by john · 0 comments

john commented

2026-08-23 20:43:32 +00:00

Owner

Several user-facing surfaces put a vocabulary to the user without ever naming it, so the reader has to already know the answer in order to answer.

Scoped by a goal-backward inventory of every workflow, skill and reference presentation site. About 50 ask sites were checked, and the codebase defines its vocabulary at the point of use almost everywhere - audit.md, docs-verify.md, progress.md, triage-gate.md, execute.md and cad-land's publish list all check out clean. This is PHASE-sized, not milestone-sized.

The eight risk-surface tokens are put to a user without their legend

One root cause, three sites:

references/review-triggers.md:562 - the first-fire ask every project hits once, at the only gate that blocks at every stakes level. The model reads the eight definitions at :532 and is then told "Do NOT compose the options at this site... add nothing to it", so an inconclusive scan offers raw tokens like api_contract with no definition.
workflows/config.md:209 - the --surfaces re-entry, worse because that path never passes the legend at all.
references/config-catalog.md:66 - the waive_routing_floor row, the only enum in that table that says "same eight categories as surfaces" instead of listing them.

Budget note

All three files are weight-budgeted and need their pins moved in the same commit.

Standing question this raises

The budget rule currently pushes against spending bytes on human-facing copy, so a surface whose job is explaining something to a person competes with prose written for a model. Worth deciding explicitly that user-facing copy earns its budget.

Checked and probably not worth scoping

minimalism-review.md:60 leaves high/medium undefined between its two named ends, and audit.md:197 uses a missing-uat break code its own enumeration at :94 omits.

Not IVW-01

That requirement reads "user-triggerable entry point and its menu stops offering the same set twice", both delivered. Naming the eight is nowhere in it.

Moved out

This issue originally carried a second cluster - refusal copy that names the condition and not the remedy, in bin/lib/publish-decision.mjs and planning.mjs. That is the same defect as #238 over the same lines, so it moved there rather than being fixed twice.

Moved to GitHub: https://github.com/crenshawdev/cadence/issues/96

This project's tracker is now GitHub; this repository remains the public archive. Closed here as migrated, not as resolved.

Several user-facing surfaces put a vocabulary to the user without ever naming it, so the reader has to already know the answer in order to answer. Scoped by a goal-backward inventory of every workflow, skill and reference presentation site. About 50 ask sites were checked, and the codebase defines its vocabulary at the point of use almost everywhere - `audit.md`, `docs-verify.md`, `progress.md`, `triage-gate.md`, `execute.md` and `cad-land`'s publish list all check out clean. This is PHASE-sized, not milestone-sized. ## The eight risk-surface tokens are put to a user without their legend One root cause, three sites: 1. `references/review-triggers.md:562` - the first-fire ask every project hits once, at the only gate that blocks at every stakes level. The model reads the eight definitions at `:532` and is then told "Do NOT compose the options at this site... add nothing to it", so an inconclusive scan offers raw tokens like `api_contract` with no definition. 2. `workflows/config.md:209` - the `--surfaces` re-entry, worse because that path never passes the legend at all. 3. `references/config-catalog.md:66` - the `waive_routing_floor` row, the only enum in that table that says "same eight categories as surfaces" instead of listing them. ## Budget note All three files are weight-budgeted and need their pins moved in the same commit. ## Standing question this raises The budget rule currently pushes against spending bytes on human-facing copy, so a surface whose job is explaining something to a person competes with prose written for a model. Worth deciding explicitly that user-facing copy earns its budget. ## Checked and probably not worth scoping `minimalism-review.md:60` leaves `high`/`medium` undefined between its two named ends, and `audit.md:197` uses a `missing-uat` break code its own enumeration at `:94` omits. ## Not IVW-01 That requirement reads "user-triggerable entry point and its menu stops offering the same set twice", both delivered. Naming the eight is nowhere in it. ## Moved out This issue originally carried a second cluster - refusal copy that names the condition and not the remedy, in `bin/lib/publish-decision.mjs` and `planning.mjs`. That is the same defect as #238 over the same lines, so it moved there rather than being fixed twice. --- **Moved to GitHub: https://github.com/crenshawdev/cadence/issues/96** This project's tracker is now GitHub; this repository remains the public archive. Closed here as migrated, not as resolved.