@ericrisco/rsc 2.0.20 → 2.2.0

package/skills/orient/references/explain-ladder.md

@@ -0,0 +1,93 @@
+# The explain ladder
+
+Text → diagram → HTML page → video. Climb one step per clear sign that the person does not follow,
+or go straight to the step they ask for. Each step replaces the last one; it does not add to it.
+
+## Step 1 — text
+
+The three rules of `../SKILL.md`: STE, stands alone, short. Most answers stop here.
+
+## Step 2 — one diagram in the chat
+
+Pick the **smallest** form that carries the point. One form per answer. Two lines of prose beside it,
+then stop.
+
+| The question is about | Draw |
+|---|---|
+| Logic, an algorithm, a decision | pseudocode |
+| What calls what at runtime | call tree |
+| UI structure | component tree, with state and module boundaries |
+| Which file does what | shallow file tree, one comment per entry |
+| Flow between pieces over time | Mermaid sequence or flow diagram |
+| Steps that branch | ASCII flow with boxes and arrows |
+| What changes in a shape that exists | `diff`, in the shape of the topic |
+| Nothing with a shape | prose — say so, no decorative diagram |
+
+Rules:
+
+- **Only the parts that answer the question.** Drop the rest of the system.
+- **Real names.** Real paths, functions, state values. `ServiceA → ServiceB` explains nothing.
+- **A diff in the shape of the topic.** A layout change is a file-tree diff; a control-flow change is
+  a pseudocode diff. Show the whole block instead when most of it is new.
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+```diff
+ src/
+ ├── commands/
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+## Step 3 — one HTML page
+
+For layout, visual state, a dense comparison, or someone who knows **nothing** about the topic.
+
+- One self-contained file. Big pictures first, words second. Inline SVG or plain HTML boxes; no chart
+  library. Readable on a phone.
+- The picture carries the idea; the words label it. If the page still makes sense with the text
+  removed, it works. A caption per picture, not a paragraph.
+- From zero: everyday objects only, no term before it is shown, and one line at the end on what the
+  simplification left out.
+- Inside a product, borrow its colours, type and spacing. Never invent an identity.
+
+Shape of a from-zero page:
+
+```text
+one sentence  : what this thing is, in words a stranger would use
+big picture 1 : the thing, drawn
+big picture 2 : the thing doing its job, step by step
+one line      : the part people get wrong
+one line      : what this left out (only if it left something out)
+```
+
+Write it, then open it (`open path/to/explain-<topic>.html`).
+
+## Step 4 — video, only on request
+
+An animated explainer (3Blue1Brown style) for something that moves: a process over time, a
+transformation, an algorithm running. It costs time and often an API key (narration, e.g.
+ElevenLabs) or local compute. So:
+
+- Offer it in one line. Never build it unasked.
+- On yes, use the catalog's video skill (`remotion-video`). If it is not installed, `suggest` offers it.
+
+## Anti-patterns
+
+| Anti-pattern | Do this instead |
+|---|---|
+| Four forms because each adds a little | One form, the smallest that answers |
+| The whole system when asked about one path | Draw the path, drop the rest |
+| A diagram to look thorough | Answer in prose, say there is nothing to draw |
+| Defining a term with two more terms | Show the thing, then name it |
+| Simplifying until it is wrong | Keep it true; name what you dropped |
+| Jumping to the HTML page on the first question | Climb one step per sign |

package/skills/orient/references/orientation-contract.md

@@ -1,34 +1,86 @@
 # Orientation contract
 
-The single definition of how the harness keeps the user oriented. The `orient` skill owns
-it; other skills reference this file in a short footer instead of copying it.
+The one definition of how the harness talks to the person. The `orient` skill owns it. Other skills
+point here from a short footer instead of copying it.
 
-## The rule
+## Voice: STE, adapted
 
-**No turn ends in seco (dead-end).** Every turn that finishes an action, reaches a fork, or
-could leave the user unsure closes with the brújula block.
+STE (Simplified Technical English, ASD-STE100) is the controlled language of aircraft maintenance
+manuals. Its rules are measurable. Apply them about 80%: in the user's language, without the
+900-word dictionary.
+
+| Rule | Limit | Example |
+|---|---|---|
+| One idea per sentence | 1 | "Instalé la skill. Ahora reinicia la sesión." |
+| Sentence length | ≤ 20 words for an instruction, ≤ 25 to describe | — |
+| Paragraph length | ≤ 6 sentences, one topic | — |
+| Active voice | always in instructions | "El test comprueba X", not "X es comprobado" |
+| Instruction first, then the reason | — | "Haz backup. Si no, pierdes los datos." |
+| One word, one meaning | — | Do not call the same thing "skill", "módulo" and "plugin" |
+| Noun stacks | ≤ 3 words | "fichero de perfil", not "fichero de configuración de perfil de usuario" |
+| Warnings | the order first, the risk next | "No borres `.rsc/`. Los hooks dejan de funcionar." |
+| Lists | vertical, for anything with steps or more than 3 items | — |
+
+Not STE: soften it when a rule would cost meaning. Precision beats the limit.
+
+## Stand-alone answers
+
+The reader did not see your reasoning, your tool output, or your plan. They may have skipped earlier
+messages. So:
+
+- Name things. "El arreglo de las rutas con espacio", not "ese arreglo".
+- No back-references the reader cannot resolve: "el segundo commit", "lo de antes", "como dije".
+- A term you introduced three turns ago gets a short gloss again if it matters now.
+- One sentence of context is enough. Never retell the session.
+
+Test: could someone read only this message and act on it? If not, add the missing sentence.
+
+## Short
+
+- Lead with the answer. Then what the person must do or decide.
+- Cut preambles, recaps of what they said, and summaries of what you just wrote.
+- A table or a list beats a paragraph when there are parallel items.
+- If it does not change what the reader understands or does, delete it.
+
+## Register
+
+`technical_level` in `02-DOCS/wiki/harness/user-profile.md` sets the vocabulary:
+
+- `technical` — use the precise term directly. No 101 explanations.
+- `non-technical` or `mixed` — plain words. One everyday analogy per new idea: things a person has
+  held (keys, boxes, a queue at a counter, a light switch). Never explain an unknown with another
+  unknown. When a technical word is unavoidable (a command, a file), say what it does in the same
+  sentence.
+- No profile — analogies, and ask once: "¿Te hablo en lenguaje técnico o con analogías?".
+
+Simple is never false. If an analogy leaves something important out, say what in one line.
+Simple is never childish: adult tone, no baby talk, no exclamation marks.
+
+`accompaniment_level:` and `accompaniment:` (the L0–L3 dial) are retired keys from older profiles. Ignore them.
 
 ## The brújula block
 
+```text
+📍 Dónde estás — the state, one sentence that stands alone
+✅ Qué has hecho — one line, only when something was done
+🧭 Por qué — one sentence, only when a decision was made
+➡️ Siguiente — 1-3 concrete options, ending in a question
 ```
-📍 Dónde estás — the project phase/state (the map)
-✅ Qué acabas de hacer — one line, in the user's language
-🧭 Por qué — the technical why, scaled to the dial
-➡️ Siguiente — 1-3 concrete options, ending in a question. Never in seco.
-```
-
-## Calibration (the dial)
 
-Read `02-DOCS/wiki/harness/user-profile.md`. Two fields combine: `accompaniment_level` (L0 | L1 | L2 | L3) sets how deep the block goes; `technical_level` (non-technical | mixed | technical) sets the vocabulary. A profile written by an older `onboard` may carry `accompaniment:` instead — it is the same dial; read it, and write `accompaniment_level` the next time you touch the profile.
+- 📍 and ➡️ every time. ✅ and 🧭 only when they carry something.
+- Each line follows the voice above: one sentence, stands alone.
+- No turn ends in seco: a turn that finishes an action, reaches a fork, or could leave the person
+  unsure ends with the block.
+- Outside any artifact. A text meant to be copied (email, post) is separated from the block.
 
-- **L0 — cavernícola:** only `✅` + `➡️`, one option, yes/no question.
-- **L1 — breve:** the four lines; one line of why.
-- **L2 — explica decisiones:** the four lines; justify the relevant decision; real forks.
-- **L3 — acompañamiento total:** the four lines, full why, many orienting questions, each option in plain language.
+## The ladder
 
-`technical_level` is orthogonal (plain language for `non-technical` even at L0; skip 101s for `technical` even at L3). Missing profile → assume `non-technical` + **L3** and offer to set the dial.
+Text first. One step up per clear sign that the person does not follow, or when they ask for a step.
+Detail → `explain-ladder.md`.
 
 ## Division of labor
 
 - `orient` guides the **person** (this contract).
 - `suggest` equips the **session** ("install the missing skill?"). Defer install prompts to it.
+- `unslop` cleans **text that leaves the session** (emails, posts, READMEs): AI tells out, human
+  register in.

package/skills/parallel/SKILL.md

@@ -120,7 +120,7 @@ This is where parallel work is actually finished. In order:
 
 Only after the combined suite is green is the parallel batch done. Hand the merged, green result back to the phase that called you (usually `implement`, heading for `verify`).
 
-**How loud.** Match the accompaniment level in `02-DOCS/wiki/harness/user-profile.md`: it sets how much of the independence reasoning, the frozen contracts, the briefs and the seam check you narrate, and nothing else. At the tersest level you still run the independence test and the combined-suite gate in full — silently, but completely.
+**What to say.** In chat, say only what the reader needs, in the `orient` voice: the partition, any frozen contract, and each reconcile conflict with its fix — one line each. The register (technical or with analogies) comes from `technical_level` in `02-DOCS/wiki/harness/user-profile.md`. However short the report, you still run the independence test and the combined-suite gate in full.
 
 ## Anti-patterns → STOP
 

package/skills/parallel/evals/cases.yaml

@@ -32,7 +32,7 @@ should_not_trigger:
     why: "The red→green→refactor TDD loop lives inside implement; parallel runs several such loops at once but never replaces the discipline within a single unit."
 
 capability:
-  - scenario: "User asks: 'I have four tasks left on the plan: (a) add the users repository, (b) add the invoices repository, (c) add a field to the orders migration, (d) add another field to the same orders migration. They feel independent — fan them out across subagents and merge when done.' (FastAPI stack noted in the plan; accompaniment level L2 in the profile.)"
+  - scenario: "User asks: 'I have four tasks left on the plan: (a) add the users repository, (b) add the invoices repository, (c) add a field to the orders migration, (d) add another field to the same orders migration. They feel independent — fan them out across subagents and merge when done.' (FastAPI stack noted in the plan; technical_level: technical in the profile.)"
     must_include:
       - "Runs the independence test pairwise and correctly identifies that (c) and (d) touch the SAME orders migration/file, so they are NOT independent and must be one serial unit — not two parallel units"
       - "Partitions into a valid plan: (a) and (b) as disjoint parallel units, (c)+(d) collapsed into a single serial unit, with the partition written down before dispatch"
@@ -41,4 +41,4 @@ capability:
       - "Each unit keeps its own red→green→refactor (delegated to implement + the FastAPI testing reference); parallel does not relax the TDD discipline inside a unit"
       - "Gathers ALL units, checks each against its done-check before merge, then reconciles: merges, resolves conflicts by hand, folds decision logs into 02-DOCS/wiki/sdd/decisions.md"
       - "Runs the COMBINED suite across the merged result and refuses to call it done on green-in-isolation; if the seam is red, routes to debug rather than guessing"
-      - "Adapts orchestration verbosity to L2 (shows partition, frozen contracts, and each reconcile conflict with its fix) and hands the green result back to implement → verify"
+      - "Reports briefly in technical terms (the partition, frozen contracts, and each reconcile conflict with its fix, one line each) and hands the green result back to implement → verify"

package/skills/plan/SKILL.md

@@ -48,7 +48,7 @@ Pydantic model or a Go method on a struct — it can, because the contract is un
 3. **The Knowledge map** — `02-DOCS/wiki/index.md` points at `02-DOCS/wiki/stack/*` and prior
    plans/decisions. Reusing what the project already settled is the difference between a plan and
    scope drift.
-4. **The dial** — `02-DOCS/wiki/harness/user-profile.md` (see below).
+4. **The profile** — `technical_level` in `02-DOCS/wiki/harness/user-profile.md` (see below).
 
 ## What a plan contains
 
@@ -95,18 +95,14 @@ phase's default tier is **`heavy`**. Routing is off unless `models.enabled: true
 `02-DOCS/wiki/sdd/config.yaml`; the resolution order, the announce rule and the model table live in
 `../sdd/references/model-routing.md`. Routing off or no profile → session model, silently.
 
-## Adapting to the dial
+## Talking about the plan
 
-The accompaniment level in `02-DOCS/wiki/harness/user-profile.md` (owned by `../init/SKILL.md`)
-changes how much you *say*, never whether a section exists. Even at L0 the plan is complete; it is
-just quiet.
-
-| Level | How `plan` behaves |
-| --- | --- |
-| **L0** | Terse plan, no narration in chat — write the file, point to it. |
-| **L1** | Same artifact, one line of *why* on the top architectural decision. |
-| **L2** | Justify each significant design choice in the artifact; surface the trade-offs weighed. |
-| **L3** | Walk a non-technical user through the architecture in plain language, define terms inline, and ask about constraints you cannot infer — one focused question at a time. |
+The artifact is complete regardless of who reads it: every section, each significant design choice
+justified with the trade-offs weighed. In chat, say only what the reader needs, in the `orient`
+voice: point to the file and give one line of *why* on the top architectural decision. The register
+comes from `technical_level` in `02-DOCS/wiki/harness/user-profile.md` (set by `../init/SKILL.md`):
+for a `non-technical` reader, explain the architecture with an everyday analogy and define each term
+inline. Ask only about constraints you cannot infer.
 
 ## Anti-patterns
 
@@ -124,7 +120,7 @@ just quiet.
 ## Always propose isolation before the build
 
 Once the plan is written, **always propose isolating the work in a git worktree/branch** before any
-code is implemented — every feature, not just the risky ones. One line, calibrated to the dial:
+code is implemented — every feature, not just the risky ones. One line:
 
 > *"Antes de implementar, ¿aíslo este trabajo en un worktree/rama propia (`../worktrees/SKILL.md`)
 > para no tocar tu rama actual? (recomendado)"*

package/skills/review/SKILL.md

@@ -24,7 +24,7 @@ The discipline is the same in both directions: **every finding and every rebutta
 
 1. `02-DOCS/wiki/sdd/specs/<slug>.md` and `02-DOCS/wiki/sdd/plans/<slug>.md` — what the diff was *supposed* to do. A review with no spec is a review of vibes.
 2. `02-DOCS/wiki/sdd/constitution.md` — the project's non-negotiables (stack canon, quality bars, conventions). Constitution violations are findings even when the code "works".
-3. `02-DOCS/wiki/harness/user-profile.md` — the accompaniment dial (see "Narration dial" below).
+3. `02-DOCS/wiki/harness/user-profile.md` — `technical_level`, the register (see "How a review reads" below).
 
 If there is no spec/plan (someone jumped straight to code), say so and review against the constitution + the diff's own stated intent. Don't pretend a spec exists.
 
@@ -247,18 +247,15 @@ When you've processed the review, summarize for the reviewer (and the decisions
 | "I'll approve it, the issues are minor" | If they're truly minor, label them nits and approve. If they block, don't approve. No mushy middle. |
 | "No spec, so I'll just eyeball it" | Say there's no spec and review against the constitution + stated intent. Don't fake a baseline. |
 
-## Narration dial
+## How a review reads
 
-Read the level from `02-DOCS/wiki/harness/user-profile.md`. It changes what a review *shows*, never its rigor — every level runs the same passes and the same evidence bar. No profile → default L2 and proceed; don't stall a review to ask for a dial setting.
+Read `technical_level` from `02-DOCS/wiki/harness/user-profile.md`. It changes the words, never the rigor — every reader gets the same passes and the same evidence bar. No profile → use analogies and proceed; don't stall a review to ask.
 
-- **L0** — verdict + the blocker list, terse. `CHANGES REQUESTED: 1 blocker (auth, documents.py:42), 1 nit. Fix the auth scope and re-run verify.`
-- **L1** — each finding gets its one-line *why*.
-- **L2** — full finding format (where/why/repro/fix); explain why each blocker blocks.
-- **L3** — the above plus teaching: name the defect class (IDOR, N+1, TOCTOU), why the boundary matters, and how to not reintroduce it. For non-technical authors, translate the impact ("any logged-in person could read everyone else's documents").
+In the `orient` voice: the verdict first, then the blocker list — e.g. `CHANGES REQUESTED: 1 blocker (auth, documents.py:42), 1 nit. Fix the auth scope and re-run verify.` Each finding keeps its full format (where/why/repro/fix) and names its defect class (IDOR, N+1, TOCTOU). For a `non-technical` author, translate the impact ("any logged-in person could read everyone else's documents").
 
 ## Model tier — `heavy` (opt-in routing)
 
-This phase's default model tier is **`heavy`** — adversarial diff reading is where the strongest model pays off most. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the narration dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+This phase's default model tier is **`heavy`** — adversarial diff reading is where the strongest model pays off most. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch in one line when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
 
 ## Where this writes
 

package/skills/roast-me/SKILL.md

@@ -119,4 +119,4 @@ Output the roast report as formatted markdown.
 
 ## Orientación (siempre)
 
-Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/sdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdd
-description: "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the accompaniment dial from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill."
+description: "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the user's register from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill."
 tags: [sdd, spec, workflow, plan]
 recommends: [sdd-init, constitution, specify]
 profiles: [core, full]
@@ -13,7 +13,7 @@ origin: risco
 
 `sdd` is the **engineering counterpart of the `harness`**. The harness runs the chaos → knowledge loop (inbox → `02-DOCS` wiki). `sdd` runs the **intent → shipped software** loop, and it writes the artifacts of that loop — constitution, specs, plans, decisions — into the same `02-DOCS/wiki/sdd/` so the project's knowledge grows with every feature instead of leaking into chat history.
 
-This skill does **not** do a phase itself. It is the dispatcher: it names the method, reads how much accompaniment you want, tells you which phase you are in, and hands off to the phase skill that owns the work. Each phase skill, when it finishes, points you at the next one — so once you enter the chain you rarely come back here.
+This skill does **not** do a phase itself. It is the dispatcher: it names the method, reads which register you want (technical or with analogies), tells you which phase you are in, and hands off to the phase skill that owns the work. Each phase skill, when it finishes, points you at the next one — so once you enter the chain you rarely come back here.
 
 ## The method in one breath
 
@@ -117,20 +117,16 @@ to `02-DOCS/wiki/sdd/` as it goes, so the work stays reviewable after the fact.
 - **A hard failure** it can't resolve (a red test it can't green → `debug`; an `analyze` contradiction).
 - **Destructive / irreversible / outward-facing actions** — push, merge, delete, secrets. `ship` (PR/merge) still confirms: autopilot drives the **build**, not the **release**.
 
-Run the fan-out on the `developer` subagent as usual, and narrate at the accompaniment dial's volume (L0: near-silent, just show artifacts; L3: explain each phase as it passes). Autopilot changes **when you ask**, never **what gets written** — every artifact and gate-check still happens; you just don't block on a human between them.
+Run the fan-out on the `developer` subagent as usual, and narrate in the `orient` voice: name each phase as it passes and show its artifact, one line each. Autopilot changes **when you ask**, never **what gets written** — every artifact and gate-check still happens; you just don't block on a human between them.
 
-## Read the accompaniment dial first
+## Read the register first
 
-Before dispatching, read `02-DOCS/wiki/harness/user-profile.md` and adapt — exactly as every rsc skill does. The dial sets **how much you explain and how many questions you ask at each gate**, not whether the gates exist.
+Before dispatching, read `technical_level` in `02-DOCS/wiki/harness/user-profile.md` — exactly as every rsc skill does. It picks the register (technical terms, or plain words with analogies); it never changes whether the gates exist. Speak in the `orient` voice:
 
-| Level | At each phase | At gates (clarify / analyze / decisions) |
-| --- | --- | --- |
-| **L0** "cavernícola" | Name the phase, do it, show the artifact. Minimal prose. | Ask only the questions that actually change the outcome. |
-| **L1** "breve" | One line of *why this phase now*. | One-line rationale per question. |
-| **L2** "explica decisiones" | Justify each significant choice as you go. | Walk the trade-offs before the user picks. |
-| **L3** "acompañamiento total" | Explain the phase, why it matters, what it produces. | Ask broadly, teach the SDD reasoning, narrate every decision. |
+- **At each phase:** name the phase, give one line of *why this phase now*, do it, show the artifact.
+- **At gates** (clarify / analyze / decisions): ask only the questions that actually change the outcome, each with its trade-off and a recommendation.
 
-If there is no profile yet, default to **non-technical + ask the two harness gauging questions** (technical level, accompaniment level) before dispatching, and persist them — that is the harness's job and `sdd` honors it.
+If there is no profile yet, use analogies and ask once **"technical or with analogies?"** before dispatching, and persist the answer — that is `init`'s job and `sdd` honors it.
 
 ## Per-phase model routing (opt-in)
 
@@ -144,7 +140,7 @@ execution, light on ship/worktrees/sdd-init).
 It is **off by default** (`models.enabled: false`). When the user opts in, each phase applies it
 two ways: **programmatically** — dispatching `Task`/`parallel` subagents on the tier's model
 (real routing, e.g. Claude Code) — and **advisorily** — announcing the recommended switch at the
-phase boundary, gated by the accompaniment dial, for inline work and assistants that can't switch
+phase boundary, in one line, for inline work and assistants that can't switch
 programmatically. Never switch unasked, never claim a switch a tool can't make, and skip routing
 on trivial one-line changes. The `sdd` dispatcher itself never routes (staying on the session
 model); `parallel` has no fixed tier (each unit inherits the tier of its work). Full protocol,
@@ -234,7 +230,7 @@ Include current phase, active artifacts, last verdict, completed tasks, next ste
 | "I get the feature, I'll just start coding." | That is the failure SDD prevents. At minimum write the spec; the artifact is the contract. |
 | "`sdd` should write the spec itself." | No. `sdd` dispatches. Invoke `specify` — it owns the spec and asks the right questions. |
 | "Clarify and analyze are bureaucracy, skip them." | Skipped gates are where drift hides. Run them; only pass through if the change is genuinely trivial and you say so. |
-| "Profile says L0, so I'll skip the gates to be terse." | L0 changes verbosity, not the method. Fewer words, same gates. |
+| "The user wants it short, so I'll skip the gates to be terse." | Short changes the words, not the method. Fewer words, same gates. |
 | "I'll keep the plan in chat, it's faster." | Chat is not durable. Write it under `02-DOCS/wiki/sdd/` or the next session is blind. |
 | "I'll skip `sdd-init`; I remember the test command." | The runtime contract belongs in `config.yaml`, not memory. |
 | "I'll load every skill into the subagent." | That contaminates context. Use registry -> selected paths -> compact rules. |

package/skills/sdd/evals/README.md

@@ -48,8 +48,8 @@ the skill — or these rubrics — needs work.
 - This is **LLM-as-judge / human-in-the-loop**, not deterministic. Use a consistent grader
   (same model + rubric) across A/B to keep the comparison fair.
 - The headline differentiators for `sdd`: it **dispatches, it does not perform a phase**; it
-  states the method ("the artifact is the contract"), reads the **accompaniment dial** and
-  adapts verbosity (not the gates), presents the **chained phase map**, applies the **invoke
+  states the method ("the artifact is the contract"), reads the **register** (`technical_level`)
+  and speaks in the orient voice (never skipping gates), presents the **chained phase map**, applies the **invoke
   rule** and the **skip rules** honestly, and writes artifacts under `02-DOCS/wiki/sdd/`.
 - Key confusables to watch: "write the spec" is `specify`, not `sdd`; "set the principles" is
   `constitution`; "open the PR" is `ship`; "build 01-TOOLS/02-DOCS" is `harness`. If the agent

package/skills/sdd/evals/cases.yaml

@@ -1,7 +1,7 @@
 skill: sdd
 
 # Cases for the rsc-sdd "sdd" dispatcher / front door.
-# sdd states the SDD method, reads the accompaniment dial from
+# sdd states the SDD method, reads the user's register (technical_level) from
 # 02-DOCS/wiki/harness/user-profile.md, and ROUTES to the right phase skill in
 # the chain constitution -> specify -> clarify -> plan -> tasks -> analyze ->
 # implement -> verify -> review -> ship (debug/worktrees/parallel on demand).
@@ -61,10 +61,10 @@ should_not_trigger:
     why: "A concrete stack build with a named framework is the nextjs stack skill. sdd is process, not stack; it would defer build specifics to nextjs rather than fire itself."
 
 capability:
-  - scenario: "A developer at accompaniment level L1 says: 'I've got a rough idea for a feature and I want to build it the spec-driven way, end to end. Where do I begin?' Show how the dispatcher opens the engagement."
+  - scenario: "A developer whose profile says technical_level: technical says: 'I've got a rough idea for a feature and I want to build it the spec-driven way, end to end. Where do I begin?' Show how the dispatcher opens the engagement."
     must_include:
       - "States the SDD method in brief: decide what & why before how, write it down, each artifact gates the next ('the artifact is the contract')"
-      - "Reads (or notes it should read) 02-DOCS/wiki/harness/user-profile.md for the accompaniment dial and, at L1, gives a one-line why per step rather than long explanations"
+      - "Reads (or notes it should read) technical_level from 02-DOCS/wiki/harness/user-profile.md and, being technical, uses technical terms directly with a one-line why per step rather than long explanations or analogies"
       - "Presents the chained phase map: sdd-init -> constitution -> proposal? -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship -> archive, with debug/worktrees/parallel on demand"
       - "Includes sdd-init as step zero when 02-DOCS/wiki/sdd/config.yaml is missing, and explains that it detects test commands, strict TDD and .rsc/skill-registry.json"
       - "Applies the invoke rule: a fuzzy idea with no spec on disk routes to specify (and notes constitution runs once per project if not yet present)"
@@ -85,6 +85,6 @@ capability:
       - "Names the three tiers — heavy (deep reasoning), balanced (execution), light (mechanical) — and that each phase has a default tier"
       - "States the default quality-biased mapping: heavy on constitution/plan/analyze/review/debug, balanced on specify/clarify/tasks/implement/verify, light on ship/worktrees/sdd-init"
       - "Says routing is OFF by default (models.enabled:false) and lives in the models block of 02-DOCS/wiki/sdd/config.yaml, written by sdd-init; turning it on is the user's choice"
-      - "Explains the two application layers: programmatic (dispatching Task/parallel subagents on the tier's model, e.g. Claude Code) and advisory (announcing the recommended switch at the phase boundary, gated by the accompaniment dial)"
+      - "Explains the two application layers: programmatic (dispatching Task/parallel subagents on the tier's model, e.g. Claude Code) and advisory (announcing the recommended switch at the phase boundary, in one line)"
       - "Is honest about limits: never switches unasked, never claims a model switch an assistant cannot make, and skips routing on trivial one-line changes"
       - "Points to references/model-routing.md for the full protocol, per-assistant mechanism, and provider→model table rather than inventing model names inline"

package/skills/sdd/references/model-routing.md

@@ -92,7 +92,7 @@ The user owns this. They change a phase by adding it to `models.overrides` (e.g.
 
 ## How a phase applies the profile (the procedure)
 
-Run this at the start of any SDD phase, after reading the accompaniment dial:
+Run this at the start of any SDD phase, after reading the user profile:
 
 1. **Read** `models` from `02-DOCS/wiki/sdd/config.yaml`. If the block is absent or
    `enabled: false` → **do nothing**: honor the session model, say nothing about models.
@@ -106,7 +106,7 @@ Run this at the start of any SDD phase, after reading the accompaniment dial:
      model and is the most reliable application — prefer it.
    - **Advisory (all assistants, inline work).** If the resolved model differs from the current
      session model and the work isn't being delegated, **announce** it at the phase boundary,
-     gated by the accompaniment dial (below), and give the switch command for the active
+     in one line (below), and give the switch command for the active
      assistant (mechanism table below). Never block — the human may decline and continue.
 5. **Skip routing entirely** for a one-line / trivial change, exactly as the SDD skip rule says
    for the rest of the chain. Ceremony serves shipping, not the other way around.
@@ -114,16 +114,9 @@ Run this at the start of any SDD phase, after reading the accompaniment dial:
    Log it to `02-DOCS/wiki/sdd/decisions.md` only when the choice actually mattered (e.g. you
    overrode a tier for a hard plan) — not on every phase.
 
-### Announcement volume by accompaniment dial
+### How to announce a switch
 
-The dial controls how loudly you announce a switch; it never changes whether routing happens.
-
-| Level | On a model switch you… |
-| --- | --- |
-| **L0** "cavernícola" | Switch/dispatch silently. One short line only if the user must act (e.g. "para esta fase conviene opus: `/model opus`"). |
-| **L1** "breve" | One line: which tier/model and the one-word why. |
-| **L2** "explica decisiones" | Name the tier, the model, and why this phase warrants it; give the switch command. |
-| **L3** "acompañamiento total" | Explain the tier system as it applies here, the cost/quality trade-off, and how to override in config. |
+Announcing never changes whether routing happens. A programmatic dispatch is silent. When the user must act, say it in one line, in the `orient` voice: the tier, the model, the one-word why, and the switch command (e.g. "para esta fase conviene opus: `/model opus`"). Explain the tier system or how to override it in config only when the user asks.
 
 ## Per-assistant switch mechanism
 
@@ -194,7 +187,7 @@ tier you didn't use.
 | --- | --- |
 | "Routing sounds good, I'll switch models even though the user never enabled it." | It's opt-in. `enabled: false` (and a missing block) means honor the session model and say nothing. |
 | "I'll tell the user I switched to Opus." (on an assistant with no programmatic switch) | You can't switch there. Announce the tier and the command; never claim a switch you didn't make. |
-| "L0 means terse, so I'll skip routing." | L0 changes words, not behavior. Route the same; just announce silently (or only when the user must act). |
+| "The user wants it short, so I'll skip routing." | Short changes words, not behavior. Route the same; announce only when the user must act. |
 | "It's a one-line typo fix but the phase is `review`, so → heavy." | Skip routing on trivial changes, like the rest of the chain. Don't spin up the expensive model for a copy tweak. |
 | "I'll log the model on every phase." | Log to `decisions.md` only when the model choice mattered. The envelope `model` field already records the routine case. |
 | "config has no `models` block, I'll assume the defaults are active." | A missing block means routing is **off**. Defaults describe what `sdd-init` *writes*, not an implicit on-state. |

package/skills/sdd-init/SKILL.md

@@ -23,14 +23,14 @@ Read-only first:
 
 - `package.json`, lockfiles, `pnpm-workspace.yaml`, `pyproject.toml`, `requirements.txt`, `go.mod`, `pubspec.yaml`, `Dockerfile`, `.github/`.
 - Existing `02-DOCS/wiki/sdd/config.yaml`, if present.
-- `02-DOCS/wiki/harness/user-profile.md`, if present, for accompaniment level only.
+- `02-DOCS/wiki/harness/user-profile.md`, if present, for `technical_level` (the register) only.
 - `.rsc/skill-registry.json`, if present, to decide whether it is stale or missing.
 
 If `02-DOCS/` does not exist, create only the `02-DOCS/wiki/sdd/` path needed for the config. Do not run full harness scaffolding unless the user asked for `harness`.
 
 ## Preflight Choices
 
-Ask only when the answer changes behavior; let the accompaniment level in the profile set how much you explain each trade-off.
+Ask only when the answer changes behavior; explain each trade-off in one line, in the register `technical_level` sets.
 
 | Setting | Default | Options |
 | --- | --- | --- |
@@ -77,7 +77,7 @@ Later phases use it as a cheap index — id, trigger, tags, path, installed/avai
 Calibration is the moment to make sure the relevant skills are actually present, not just indexed. Detect → propose → install:
 
 1. **Detect what this repo needs.** Use the stack you just detected, or ask the CLI: `npx @ericrisco/rsc consult "<one line: stack + what we're building>"`. Map signals to skills — e.g. `next`→`nextjs`+`design`, `go.mod`→`go`, FastAPI→`fastapi`, `*.sql`/Prisma→`postgresdb`/`prisma-orm`, Stripe→`stripe`, Dockerfile/CI→`docker`/`github-actions`, tests→`testing-*`/`e2e-testing`. The SDD phase skills (`specify`…`ship`) should already be present from `--profile core`; install any that are missing.
-2. **Show the shortlist + confirm.** List the skills with a one-line *why* each, matched to the accompaniment dial, and get a one-word confirm before touching their environment.
+2. **Show the shortlist + confirm.** List the skills with a one-line *why* each, in the user's register, and get a one-word confirm before touching their environment.
 3. **Install them yourself.** You have a terminal — run it via Bash:
    ```bash
    npx @ericrisco/rsc add <skill> [<skill> ...]

package/skills/ship/SKILL.md

@@ -35,7 +35,7 @@ git log -1 --format='%an <%ae>%n%n%b' | grep -iE 'co-authored-by.*(claude|anthro
 
 ## Read these first
 
-1. `02-DOCS/wiki/harness/user-profile.md` — the accompaniment dial (L0..L3). It sets narration only, never whether you run the safety checklist.
+1. `02-DOCS/wiki/harness/user-profile.md` — `technical_level`, the register. It sets the words only, never whether you run the safety checklist.
 2. The **review verdict** for this branch — ship runs only on `APPROVE` or `APPROVE WITH NITS`. `CHANGES REQUESTED` loops back to `implement`, not forward to ship. If there is no verdict on record, say so and treat it as a red flag: do not ship a diff that skipped `../review/SKILL.md` — offer to run it first.
 3. `02-DOCS/wiki/sdd/decisions.md` and the spec/plan slug — so the commit message and PR body describe *what shipped against which spec*, not a vague "various changes".
 
@@ -85,7 +85,7 @@ was reviewed, never that the review was any good.
 
 ## The three landing options — always present exactly three
 
-This mirrors the harness "siempre 3 opciones" pattern. Gather the one fact that changes the answer (does this repo use PRs / require review on `main`?), then present **exactly three** with an honest recommendation matched to the workflow and the accompaniment level.
+This mirrors the harness "siempre 3 opciones" pattern. Gather the one fact that changes the answer (does this repo use PRs / require review on `main`?), then present **exactly three** with an honest recommendation matched to the workflow, in the user's register.
 
 | Option | What it does | Choose it when |
 | --- | --- | --- |
@@ -201,16 +201,11 @@ The commit is the durable record. Make it describe the change and tie it to the
 
 Closing the branch (PR / merge / cleanup) is mechanical, so this phase's default tier is **`light`**. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`; when it is on, follow `../sdd/references/model-routing.md` for resolving and announcing the switch rather than from memory. Routing off or no profile → honor the session model silently, and skip routing on a one-line change. The Eric-only authorship rule is independent of the model and never relaxes.
 
-## Accompaniment dial (L0..L3)
+## What ship shows
 
-Read the level from `02-DOCS/wiki/harness/user-profile.md`. It changes what you show, **never** the safety checklist or the authorship rule. No profile → default to L2 and proceed; don't stall the ship to ask for a dial setting.
+Read `technical_level` from `02-DOCS/wiki/harness/user-profile.md`. It changes the words, **never** the safety checklist or the authorship rule. No profile → use analogies and proceed; don't stall the ship to ask.
 
-| Level | What ship shows |
-| --- | --- |
-| **L0** | Checklist run silently, recommended option in one line, execute on a yes: `Clean, rebased, authorship Eric. Recommend PR (main is protected). Open it?` |
-| **L1** | The three options as one-liners, with the recommendation and its *why*. |
-| **L2** | The full options table, the checklist results, and why the recommended option fits this repo's workflow. |
-| **L3** | L2 plus teaching, framed for a non-technical owner: what fast-forward vs `--no-ff` does to history, why a protected `main` wants a PR ("asking permission before changing the shared copy"), what squashing trades away. |
+In the `orient` voice: the checklist result in one line, the three options as one-liners, the recommendation and its *why*, then execute on a yes — e.g. `Clean, rebased, authorship Eric. Recommend PR (main is protected). Open it?`. For a `non-technical` owner, explain the recommended option with an analogy: a protected `main` wants a PR ("asking permission before changing the shared copy"). Explain fast-forward vs `--no-ff` or what squashing trades away only when asked.
 
 ## Anti-patterns → STOP
 
@@ -268,4 +263,4 @@ Ship is the end of the SDD loop for a feature. Two onward paths: the merged code
 
 ## Orientación (siempre)
 
-Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/simplify-code/SKILL.md

@@ -98,4 +98,4 @@ Stop when another edit would trade one defensible style for another without lowe
 
 ## Orientación (siempre)
 
-Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el “¿instalo la skill que falta?”.)
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/skill-scout/SKILL.md

@@ -46,7 +46,7 @@ Then, in this order and never skipping ahead:
 4. **Nothing covers it** → one sentence at the end of the work: the procedure you saw, and whether it fits as a skill or an agent. Then stop; the user decides. Their "no" ends it for this procedure for the rest of the session.
 5. **Record it either way** — `npx @ericrisco/rsc capabilities gap-log --procedure "<what YOU observed doing>" --verdict <covered-installed|covered-catalog|covered-agent|proposed-accepted|proposed-declined>`.
 
-**Scale the sentence to the dial**, never whether it appears. Read the accompaniment level in `02-DOCS/wiki/harness/user-profile.md`: at L0/L1 it is one dry line ("this looked like a procedure — worth a skill?"); at L2/L3 add why it qualified and what the skill-vs-agent difference means for them. A profile that asked for brevity still gets the observation, just not the essay.
+**One sentence, always.** In the `orient` voice: one line ("this looked like a procedure — worth a skill?") plus why it qualified. Explain the skill-vs-agent difference only if the user asks; for a `non-technical` reader (`technical_level` in `02-DOCS/wiki/harness/user-profile.md`), use an analogy. Brevity never removes the observation.
 
 **The privacy boundary is yours to hold**, not the command's — it validates shape and nothing else, and it cannot tell your description from a paraphrase of the request. `--procedure` carries *your* account of the work you did. Never the user's words. The test: if the line could be reconstructed from what they typed, it does not belong in the log.
 

package/skills/source-grounded-development/SKILL.md

@@ -105,4 +105,4 @@ Do not use this skill as a reason to delay reversible work indefinitely. If a pr
 
 ## Orientación (siempre)
 
-Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el “¿instalo la skill que falta?”.)
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)