@ericrisco/rsc 0.1.43 → 0.1.45

package/skills/parallel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parallel
-description: "Use when you have two or more genuinely independent pieces of work and want to fan them out across subagents instead of doing them one after another — disjoint scope, no shared files or state, no ordering dependency, then gather and reconcile the results. Triggers: 'do these in parallel', 'fan this out', 'split this across subagents', 'run these at the same time', 'these tasks are independent, parallelize them', 'dispatch agents for each module', 'hazlo en paralelo', 'reparte esto en subagentes', 'a la vez'. The on-demand SDD helper that implement calls when its task list has disjoint clusters; it owns the partition→dispatch→gather→reconcile discipline. NOT for sequential or data-dependent steps (serialize those), NOT the TDD loop itself (that stays inside implement), NOT git isolation (that's worktrees)."
+description: "Use when two or more pieces of work are genuinely independent — disjoint files, no shared state, no ordering edge — and should fan out across subagents, then be gathered and reconciled under a combined test suite. Decides WHAT can run concurrently; NOT the isolation it runs in (that is `worktrees`), NOT the per-unit TDD loop (that is `implement`)."
 tags: [parallel, subagents, fanout]
 recommends: []
 profiles: [core, full]
@@ -11,7 +11,7 @@ origin: risco
 
 *Parallelism is a property of the work, not a wish. Prove the pieces are disjoint, dispatch one subagent per piece with a self-contained brief, then gather and reconcile before anyone calls it done.*
 
-This is an **on-demand process skill** in the SDD chain. You reach it from `implement` (or any phase) when the work in front of you splits into pieces that could each be handed to a different person who never talks to the others. It owns one discipline: **partition → dispatch → gather → reconcile**. It does *not* own the work inside each piece — a subagent building a module still runs its own red → green → refactor loop from `implement`; this skill only orchestrates the fan-out.
+This is an **on-demand process skill** in the SDD chain. You reach it from `implement` (or any phase) when the work in front of you splits into pieces that could each be handed to a different person who never talks to the others. It owns one discipline: **partition → dispatch → gather → reconcile**. It does *not* own the work inside each piece — a subagent building a module still runs its own red → green → refactor loop from `implement`; this skill only orchestrates the fan-out. It also does not own the *place* the work runs: a clean branch or checkout to work in is `worktrees`. `parallel` decides **what can run at the same time**; `worktrees` provides **the isolation it runs in**.
 
 The whole value is in the gate at the front. Run work in parallel only when it is *actually* independent. Forcing parallelism onto coupled work does not make it faster — it makes it a merge disaster, and the time you save dispatching you lose tenfold reconciling. Most of this skill is about earning the right to parallelize.
 
@@ -75,12 +75,7 @@ Each subagent still owns its own discipline inside its scope — TDD via `implem
 
 **Per-unit model tier (when routing is enabled).** `parallel` has *no fixed tier* — this is the most concrete place per-phase model routing pays off. When `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`, give each unit the tier of the *kind of work it does*, not one tier for the whole fan-out: an implement-type unit → `balanced`, a scan/research/boilerplate unit → `light`, a unit doing genuine design or root-cause reasoning → `heavy`. Resolve the tier to a concrete model via `models.tiers` and **dispatch that subagent on that model** (e.g. Claude Code's `model` field on the Task/subagent) — real routing, independent of the session model. If routing is off or no profile exists, dispatch on the session model and say nothing. Full protocol: `../sdd/references/model-routing.md`.
 
-**The `developer` agent is the default worker.** rsc installs a `developer` subagent pinned to the **balanced** tier (Sonnet by default; the user's onboarding choice in `.rsc/developer.json`, never `light`). For implement-type units, **dispatch to the `developer` agent** (e.g. Claude Code `subagent_type: developer`) — that's the deliberate cost cap the user asked for. Only escalate a genuinely heavy unit (real design / root-cause) to a heavy model, and only when routing is enabled; otherwise the `developer` agent's balanced model is the floor and the ceiling.
-
-**Model is REQUIRED on every dispatch.** Set each subagent's model explicitly. An omitted model
-silently inherits the session's model — usually the most expensive one — and that is how a fan-out's
-cost quietly explodes. The `developer` agent already pins balanced; if you dispatch a raw subagent,
-name its tier.
+**Set the model on every dispatch — an omitted model silently inherits the session's, usually the most expensive one, and that is how a fan-out's cost quietly explodes.** rsc installs a `developer` subagent pinned to the **balanced** tier (Sonnet by default; the user's onboarding choice in `.rsc/developer.json`, never `light`). For implement-type units, **dispatch to the `developer` agent** (e.g. Claude Code `subagent_type: developer`) — that's the deliberate cost cap the user asked for. Only escalate a genuinely heavy unit (real design / root-cause) to a heavy model, and only when routing is enabled; otherwise balanced is the floor and the ceiling. If you dispatch a raw subagent instead, name its tier explicitly.
 
 ### The unit report contract (statuses & escalation)
 
@@ -96,9 +91,7 @@ change something first: add the missing interface/constraint, fix the dependency
 tier for a genuinely hard unit. An identical re-run burns budget without progress. A `BLOCKED` unit
 is a partition signal too: if it blocked on another unit, the two were not independent — re-partition.
 
-### Skill resolution feedback
-
-Every subagent result must report:
+Every subagent result must also report:
 
 ```yaml
 skill_resolution:
@@ -114,15 +107,7 @@ The orchestrator folds these into the final parallel result. If a unit claims it
 
 Wait for **all** units to report. Collect each one's diff, test output, and any decisions. Do not start merging the fast ones while slow ones are still running — partial merges create the exact shared-state races you partitioned to avoid. Check each result against its brief's done-check *before* it touches the integration branch: a unit that came back not-actually-done gets sent back, not merged hopefully.
 
-**Per-unit review gate (before merge).** For each non-trivial unit, run a fresh-eyes review of *that
-unit's diff alone* before it joins the integration branch — the same gate `implement` runs per task
-(full brief: `../implement/references/per-task-review.md`). Package the unit's diff as a file
-(`../implement/scripts/review-package <BASE> <HEAD>`), dispatch a fresh reviewer (NOT the unit's own
-implementer) with the diff path + the unit's done-check + its frozen interface, and fold
-`Critical`/`Important` findings back before merging. **Anti-pre-judging:** never tell the reviewer
-what not to flag or pre-rate severity. This is the cheap per-unit pass; the *combined* adversarial
-review over the whole merged diff is still `review`'s job at the end (RECONCILE only proves the seam
-compiles and tests green).
+**Per-unit review gate (before merge).** For each non-trivial unit, run the same fresh-eyes review `implement` runs per task, over *that unit's diff alone* — package it with `../implement/scripts/review-package <BASE> <HEAD>` and dispatch a reviewer that is **not** the unit's own implementer, given the diff path, the unit's done-check, and its frozen interface; never pre-rate severity or tell it what to skip. Fold `Critical`/`Important` findings back before merging. Full protocol: `../implement/references/per-task-review.md`. This is the cheap per-unit pass; the *combined* adversarial review over the whole merged diff is still `review`'s job at the end (RECONCILE only proves the seam compiles and tests green).
 
 ### 4. RECONCILE — merge, then prove the seam holds
 
@@ -135,28 +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`).
 
-## The accompaniment dial — how loud while fanning out
-
-Read the level from `02-DOCS/wiki/harness/user-profile.md` and match it. The dial changes how much you narrate the orchestration; it never changes the independence test or the reconcile gate.
-
-| Level | While dispatching/reconciling you show… | Questions you ask |
-| --- | --- | --- |
-| **L0** terse | the partition (batches + spine) in one block, then "merged, combined suite green" | none unless a unit fails its done-check or a contract needs freezing |
-| **L1** brief | the partition + one line of *why these are independent* | confirm the partition only where independence is borderline |
-| **L2** decisions | the partition, the frozen contracts, and each reconcile conflict with its fix | confirm before freezing a contract that constrains multiple units |
-| **L3** full | the full independence reasoning per pair, the briefs, the gather, the seam check, narrated | ask to validate the partition before dispatch; teach why the seam is the risk |
-
-L0 still runs the independence test and the combined-suite gate — silently, but completely. Terse is about words, not about skipping the gate.
-
-## When parallel is the wrong tool
-
-Be honest about this — most task lists are *mostly* serial with a few disjoint pockets, not the other way around.
-
-- **The pieces share a file or a contract.** Serialize, or freeze the contract first then fan out the rest. Do not parallelize across a live shared edit.
-- **One piece needs another's output.** That is a dependency edge, by definition sequential. Order them.
-- **There are only two tiny tasks.** Orchestration overhead (writing briefs, gathering, reconciling) can cost more than just doing them in a row. Parallelize when the units are substantial and many, not to look busy.
-- **You can't write a self-contained brief for a unit.** If you cannot describe it without referring to a sibling unit, it is not independent yet. Fix the partition or serialize.
-- **You only need isolation, not concurrency.** Wanting a clean branch/worktree to work in is `worktrees`, not this. This skill is about doing several things *at once*; isolation is about doing one thing *cleanly*.
+**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.
 
 ## Anti-patterns → STOP
 
@@ -169,33 +133,10 @@ Be honest about this — most task lists are *mostly* serial with a few disjoint
 | "I'll merge the fast unit now and the slow one when it lands." | Partial merges reintroduce the races you partitioned away. Gather all, then reconcile once. |
 | "It's only two small tasks, but parallel sounds efficient." | Orchestration overhead > the work. Just do them in a row. |
 | "The brief says 'see the other agent's output' — close enough." | That's a dependency, not independence. Serialize, or freeze the output first. |
-| "Combined suite is red, probably the slower unit — I'll tweak it." | Don't guess at the seam. Reproduce and isolate with debug. |
-| "I just want an isolated branch, so I'll use parallel." | That's isolation, not concurrency. Use worktrees. |
+| "Combined suite is red, probably the slower unit — I'll tweak it." | Don't guess at the seam. Reproduce and isolate with `debug`. |
+| "I just want an isolated branch, so I'll use parallel." | That's isolation, not concurrency. Use `worktrees`. |
 | "Routing's on, so I'll run the whole fan-out on one tier." | `parallel` has no fixed tier — give each unit the tier of its own work (scan→light, build→balanced, design→heavy). |
 
-## Red flags — stop and re-plan the partition
-
-- A subagent brief can't be written without referencing another unit → not independent; re-partition.
-- Two units both need to edit the same file / migration / barrel / type → collapse them into one serial unit.
-- Subagents are asking to "sync up" mid-run → the contract wasn't frozen; stop, freeze it, re-dispatch.
-- The combined suite is red after merge → the seam leaked; `debug` before continuing, don't checkpoint as done.
-- More open subagents than you can actually review → over-fanned; reduce the degree of parallelism.
-
-## Checklist (copy per fan-out)
-
-```text
-- [ ] PARTITION: independence test passed for every pair; batches + serial spine written down
-- [ ] Shared contracts/types/schemas FROZEN in the serial spine before dispatch
-- [ ] DISPATCH: one self-contained brief per unit (scope, goal, done-check, constraints, report-back)
-- [ ] Each brief includes selected skills, compact rules, and fallback behavior from registry
-- [ ] Each unit honors the constitution + its stack skill; TDD stays inside the unit
-- [ ] GATHER: all units reported; each checked against its done-check BEFORE merge
-- [ ] GATHER: each unit returned skill_resolution (used/missing/fallback/compact_rules)
-- [ ] RECONCILE: merged, conflicts resolved by hand, decision logs folded into 02-DOCS
-- [ ] Combined suite run across the merged result and GREEN (not just green-in-isolation)
-- [ ] Result handed back to the calling phase (usually implement → verify)
-```
-
 ## Result envelope
 
 End with:
@@ -218,17 +159,10 @@ End with:
 }
 ```
 
-## What this skill is NOT
-
-- **Not the TDD loop.** Each unit's red → green → refactor stays inside `implement`. This skill runs several of those at once; it does not replace the discipline within one.
-- **Not git isolation.** Creating a branch or worktree to work cleanly is `worktrees`. This skill is concurrency across disjoint work, not a clean room for one stream.
-- **Not the task breakdown.** Producing the ordered task list with done-checks is `tasks`; `parallel` consumes that list and decides which pieces can run together.
-- **Not the debugger.** When the combined suite goes red at the seam, switch to `debug` — don't guess which unit to blame.
-
 ## Where you are in the chain
 
 `parallel` is on-demand, callable from any phase but most often from `implement`:
 
 `constitution` → `specify` → `clarify` → `plan` → `tasks` → `analyze` → **implement** → `verify` → `review` → `ship`, with `debug` · `worktrees` · **parallel** callable on demand.
 
-**Next:** when the fan-out is reconciled and the combined suite is green, return to the phase that called you — usually `../implement/SKILL.md`, continuing the task list toward `../verify/SKILL.md`. If the seam is red, go to `debug` first. If you discover you actually needed an isolated branch rather than concurrency, that's `worktrees`.
+**Next:** when the fan-out is reconciled and the combined suite is green, return to the phase that called you — usually `../implement/SKILL.md`, continuing the task list toward `../verify/SKILL.md`. If the seam is red, go to `debug` first. If the ordered task list with done-checks does not exist yet, that is `tasks`, not this. If what you actually needed was an isolated branch rather than concurrency, that's `worktrees`.

package/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: "Use when turning an approved, clarified spec into a technical implementation plan — the SDD phase between clarify and tasks. Covers architecture and component boundaries, the public interfaces/contracts, data model and data flow, the testing strategy, sequencing, and the risk register. Triggers: 'plan this feature', 'how should we build this', 'design the architecture', 'write the implementation plan', 'plan.md', 'what's the data flow', 'how do we test this', 'what are the risks', 'we have the spec, now what'. Reads the spec under 02-DOCS/wiki/sdd/specs/ and the constitution; writes 02-DOCS/wiki/sdd/plans/<slug>.md; defers concrete stack mechanics (framework APIs, ORM, test tooling) to the relevant stack skill. NOT requirements capture (that's specify), NOT ambiguity removal (that's clarify), NOT the task breakdown (that's tasks). Honors the harness accompaniment dial."
+description: "Use when an approved, clarified spec must become a technical blueprint before any code — the SDD phase between clarify and tasks: architecture, contracts, data flow, testing strategy, sequencing and risks, at structure altitude, never framework syntax. NOT the what/why spec (that is `specify`), NOT the ambiguity sweep (that is `clarify`), NOT the task breakdown (that is `tasks`), NOT the code (that is `implement`)."
 tags: [sdd, plan, design]
 recommends: [tasks]
 profiles: [core, full]
@@ -9,213 +9,140 @@ origin: risco
 
 # Plan — the technical blueprint between spec and tasks
 
-You have a spec that says **what** and **why**. `plan` decides **how** — the architecture, the
-interfaces, the data flow, the way you'll prove it works, and the things most likely to bite you.
-It is the engineering counterpart of the spec: a spec a human signed off on becomes a plan an
-engineer (or an agent) can execute without re-deciding the shape of the system halfway through.
-
-`plan` sits fourth in the SDD chain:
+The spec says **what** and **why**. `plan` decides **how**: the components, the contracts between
+them, the data that flows, how each claim gets proven, and what is most likely to bite. It reads the
+clarified spec and the constitution, writes ONE artifact — `02-DOCS/wiki/sdd/plans/<slug>.md` — and
+hands off to `tasks`, which slices it into an ordered, independently-verifiable checklist.
 
 ```text
 constitution → specify → clarify → [ plan ] → tasks → analyze → implement → verify → review → ship
 ```
 
-It reads the clarified spec and the constitution, produces ONE artifact —
-`02-DOCS/wiki/sdd/plans/<slug>.md` — and hands off to `tasks`, which slices that plan into an
-ordered, independently-verifiable checklist.
-
-## The one rule that defines this phase
+## Decide structure, not syntax
 
-**Decide structure, not syntax.** A plan names the components, their contracts, the data that
-flows between them, and how each piece is proven. It does **not** write the framework's route
-decorators, the ORM's session boilerplate, or the test runner's flags. Those are stack mechanics,
-and they belong to the stack skill (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`,
-`../flutter/SKILL.md`, `../postgresdb/SKILL.md`). The plan says *"the orders service exposes a
-`reserve(cartId) → Reservation` operation, transactional, idempotent on cartId"*; the stack skill
-later decides whether that's a POST handler with a Pydantic model or a Go method on a struct.
+A plan names components, contracts, shapes and flows. It does not write the framework's route
+decorators, the ORM's session boilerplate or the test runner's flags — those are stack mechanics,
+owned by the stack skill (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`,
+`../flutter/SKILL.md`, `../postgresdb/SKILL.md`) at `implement` time. This altitude is what makes a
+plan reviewable against intent and slice-able by `tasks`; drop it and you get code no one approved.
 
-If you find yourself writing real code in the plan, you have dropped an altitude. Pull back up.
+```text
+reservation.reserve(cartId: CartId) -> Reservation | OutOfStock | CartNotFound
+  - idempotent on cartId (calling twice returns the same Reservation)
+  - holds stock for 15 min, then auto-releases
+  - never partially reserves: all lines or none
+```
 
-## Before you write a line
+That is the altitude. The stack skill later decides whether it becomes a POST handler with a
+Pydantic model or a Go method on a struct — it can, because the contract is unambiguous.
 
-Run this gate. Skipping it produces a plan that drifts from intent on contact.
+## Entry gate
 
-1. **Read the accompaniment dial.** Open `02-DOCS/wiki/harness/user-profile.md`. The technical +
-   accompaniment level (L0..L3) sets how much you explain and how many questions you ask — see
-   "Adapting to the dial" below. No profile yet → assume non-technical, ask the two gauging
-   questions first (the harness owns that flow).
-2. **Read the spec.** `02-DOCS/wiki/sdd/specs/<slug>.md`. If it is missing, STOP — there is nothing
-   to plan from; route to `../specify/SKILL.md`. If it still carries `[NEEDS CLARIFICATION]` markers
-   or open questions, STOP — route to `../clarify/SKILL.md`. **A plan built on an unclarified spec
-   is a guess wearing a diagram.**
-3. **Read the constitution.** `02-DOCS/wiki/sdd/constitution.md` holds the project's non-negotiables
+1. **The spec** — `02-DOCS/wiki/sdd/specs/<slug>.md`. Missing → STOP, route to
+   `../specify/SKILL.md`. Still carrying `[NEEDS CLARIFICATION]` markers or open questions → STOP,
+   route to `../clarify/SKILL.md`. A plan built on an unclarified spec is a guess wearing a diagram,
+   and every phase downstream inherits the guess.
+2. **The constitution** — `02-DOCS/wiki/sdd/constitution.md` holds the project's non-negotiables
    (stack canon, quality bars, conventions). Every architectural choice must be consistent with it;
-   when the plan needs to bend a principle, say so explicitly with a reason — don't bend it silently.
-4. **Read the Knowledge map.** The full index at `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer to it) points at existing
-   `02-DOCS/wiki/stack/*` and prior plans/decisions. Reuse what's already established. A plan that
-   reinvents a pattern the project already settled is scope drift.
-
-Only when the spec is present and clarified do you plan.
+   where the design needs to bend a principle, say so with a reason instead of bending it silently.
+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).
 
 ## What a plan contains
 
-A plan is the answer to seven questions, in this order. Each is a section of the artifact
-(template in `references/plan-template.md`). Fill them top-down; later sections lean on earlier ones.
+The sections of the artifact, in order; fill them top-down, later ones lean on earlier ones. The
+fill-in skeleton with per-section guidance is `references/plan-template.md` — use it verbatim.
 
-| # | Section | The question it answers |
+| § | Section | The question it answers |
 | --- | --- | --- |
-| 1 | Context & constraints | What spec/constitution facts pin this design down? |
+| 0 | Global constraints | Which exact values must every task honor? (verbatim, not paraphrased — a context-isolated implementer and its reviewer see nothing else) |
+| 1 | Context & constraints | Which spec/constitution facts pin this design down? Cite (`spec §Acceptance #3`), don't re-paste |
 | 2 | Architecture | What are the components and how do they fit together? |
-| 3 | Interfaces & contracts | What does each component promise to the others? |
+| 3 | Interfaces & contracts | What does each component promise the others? |
 | 4 | Data model & flow | What data exists, where it lives, how it moves and changes? |
 | 5 | Testing strategy | How will we *prove* each part does what it claims? |
 | 6 | Sequencing & dependencies | In what order can this be built and verified? |
-| 7 | Risks & open decisions | What is most likely to be wrong, and what's still undecided? |
-
-Detailed guidance and the fill-in template live in `references/plan-template.md`. The essentials of
-each section:
-
-### 1. Context & constraints
-
-Restate, in one or two lines each, the spec facts and constitution rules that actually constrain
-the design — the acceptance criteria, the non-functional bars (latency, scale, data residency),
-the stack canon. Don't re-paste the spec; cite it (`spec §Acceptance #3`). This section is the
-plan's contract with intent: if a reviewer disagrees with the design, this is where they check
-whether you misread the constraints.
+| 7 | Risks & open decisions | What is most likely to be wrong, and what is still undecided? |
+
+Three of them carry the weight and fail quietly:
+
+- **§2 Architecture** — a box-and-arrow diagram, one sentence of single responsibility per
+  component, internal vs. external marked (the arrows are the seams you will test and parallelize).
+  State the **one** decision that matters most — sync vs. async, split service vs. monolith, read
+  model vs. single table — and defend it against a constraint from §1. If two designs are genuinely
+  viable, give both, the trade-off, *and* your recommendation; leaving the reader to choose is not a
+  plan.
+- **§5 Testing strategy** — per acceptance criterion: the level that proves it (unit / contract /
+  integration / e2e), what it asserts, what it fakes to stay fast. Deciding this before code exists
+  is what makes `implement`'s TDD possible. You choose the seams; the stack skill owns the tooling.
+- **§7 Risks** — ranked, each with trigger, impact, and the mitigation or spike that retires it. A
+  plan claiming zero risk is the riskiest one. Significant decisions taken while planning also get
+  appended to `02-DOCS/wiki/sdd/decisions.md`, so later phases can trace the *why*.
 
-### 2. Architecture
-
-Name the components and draw the relationship — a small box-and-arrow diagram in a fenced block,
-plus a sentence per component stating its single responsibility. Mark each component's boundary:
-what's inside the system you're building vs. an external dependency. Show where the seams are,
-because the seams are where you'll test, mock, and parallelize later.
-
-```text
-[ client ] --HTTP--> [ api: orders ] --calls--> [ svc: reservation ]
-                            |                            |
-                            v                            v
-                     [ db: orders ]              [ external: payments ]
-```
-
-State the **one** architectural decision that matters most and why you made it (sync vs. async,
-monolith vs. split service, read model vs. single table). One real decision, defended, beats five
-hedged ones. If two designs are genuinely viable, present both with the trade-off and a
-recommendation matched to the constitution — don't leave the reader to guess which you'd ship.
-
-### 3. Interfaces & contracts
-
-For each seam in the architecture, define the contract at the **shape** level, not the
-implementation: the operation name, its inputs and outputs, its error modes, and its invariants
-(idempotent? transactional? ordered?). This is where most integration bugs are prevented or born.
-
-```text
-reservation.reserve(cartId: CartId) -> Reservation | OutOfStock | CartNotFound
-  - idempotent on cartId (calling twice returns the same Reservation)
-  - holds stock for 15 min, then auto-releases
-  - never partially reserves: all lines or none
-```
-
-Keep it language-neutral. The stack skill turns this into a typed signature, a route, or an
-interface later — and it will, because you gave it an unambiguous contract.
-
-### 4. Data model & flow
-
-Name the entities, their key fields, and their relationships — again at the model level, not DDL.
-Then trace the **flow**: for the primary scenario in the spec, follow one request from entry to
-persistence and back, naming what reads and writes each store. Call out the consistency boundaries
-(what's transactional together, what's eventually consistent) and the migration impact (new table?
-new column? backfill?). Concrete schema, indexes, and migration mechanics → `../postgresdb/SKILL.md`.
-
-### 5. Testing strategy
-
-Decide *how each claim in the spec gets proven* before any code exists — this is what makes
-`implement`'s TDD discipline possible. For each acceptance criterion, name the level that proves it
-(unit / contract / integration / e2e), what the test asserts, and what it has to fake to stay fast.
-You are choosing the *strategy* (which seams to test, what to mock, where the e2e line is); the
-stack skill owns the *tooling* (the runner, the fixtures, the assertion library). A plan whose
-testing section is "we'll add tests" has no testing strategy — name the levels and the seams.
-
-### 6. Sequencing & dependencies
-
-Order the work so each step is independently verifiable and the dependency graph is explicit. Mark
-which steps are independent (candidates for fan-out via the `parallel` phase when it's available)
-and which must be serial. This section is the bridge to `tasks`: a clean sequence here becomes a
-clean task list there.
-
-### 7. Risks & open decisions
+## The artifact
 
-List what is most likely to be wrong, ranked. For each risk: the trigger, the impact, and the
-mitigation or the spike that would retire it. Separately, log any decision still genuinely open
-(and what input would close it). Honesty here is the whole point — a plan that claims zero risk is
-the riskiest plan. Significant design decisions taken during planning also get appended to
-`02-DOCS/wiki/sdd/decisions.md` (the SDD decisions log), so later phases can trace the *why*.
+Write `02-DOCS/wiki/sdd/plans/<slug>.md`, `<slug>` matching the spec's slug exactly — one plan per
+spec, same name, because that is how `tasks`, `analyze` and `implement` find it. Then index it in
+`02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a pointer). If a plan for
+this slug already exists, update it in place and note what changed — never fork a `-v2`.
 
 ## Model tier — `heavy` (opt-in routing)
 
-This phase's default model tier is **`heavy`** — architecture, interfaces, data flow and risks are the heaviest cognitive load in the chain. 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 accompaniment 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.
+Architecture, interfaces, data flow and risk are the heaviest reasoning in the chain, so this
+phase's default tier is **`heavy`**. Routing is off unless `models.enabled: true` in
+`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
 
-Read `02-DOCS/wiki/harness/user-profile.md` and match the artifact and your narration to it:
+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: the seven sections, minimal prose, diagram + contracts + risks. No narration in chat — write the file, point to it. |
+| **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 trade-offs you weighed. |
-| **L3** | Explain-everything: walk the non-technical user through the architecture in plain language, ask about constraints you can't infer (one focused question at a time), define terms inline. |
-
-The dial changes how much you *say*, never whether the seven sections exist. Even at L0 the plan is
-complete; it's just quiet.
-
-## The artifact
-
-Write to `02-DOCS/wiki/sdd/plans/<slug>.md`, where `<slug>` matches the spec's slug exactly (one
-plan per spec, same name — that's how `tasks`, `analyze`, and `implement` find it). Use
-`references/plan-template.md` verbatim as the skeleton. Then index it in `02-DOCS/wiki/index.md`
-(the Knowledge map; root `CLAUDE.md` keeps only a short pointer) pointing at the new plan, so the harness wiki and
-every later phase can find it. If a plan for this slug already exists, update it in place and note
-what changed — don't fork a `-v2`.
+| **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. |
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality / Fix |
+| Anti-pattern | Why it fails / the fix |
 | --- | --- |
-| "I'll just write the actual code in the plan, it's faster" | You dropped an altitude. The plan owns structure; syntax is the stack skill's job at `implement`. Pull back to contracts. |
-| "The spec's a bit fuzzy but I get the gist, I'll plan around it" | A plan on an unclarified spec is a guess. STOP, route to `clarify`, then plan. |
-| "Testing strategy = 'we'll write tests'" | That's not a strategy. Name the level per acceptance criterion and what each test fakes. |
-| "Risks section feels negative, I'll keep it short" | The plan that claims no risk is the riskiest. Rank the real risks and give each a mitigation. |
-| "I'll pick the framework and ORM and config here" | Stack canon lives in the constitution; mechanics live in the stack skill. The plan stays stack-neutral above the seam. |
-| "Two designs are fine, I'll list both and let them choose" | Decide. Present alternatives only with a trade-off and a recommendation matched to the constitution. |
-| "I'll plan the whole sequence as one big step" | Then `tasks` can't slice it and nothing's independently verifiable. Break it into ordered, checkable steps. |
-| "There's already a plan for this slug, I'll start a fresh one" | Update in place and note the change. Forked plans rot; later phases read the wrong one. |
-
-## When NOT to use
-
-- Capturing what to build and why, from a fuzzy idea → `../specify/SKILL.md`.
-- Removing ambiguity / edge cases from an existing spec → `../clarify/SKILL.md`.
-- Slicing an approved plan into an ordered task checklist → `../tasks/SKILL.md`.
-- Concrete framework/ORM/test-runner mechanics → the relevant stack skill
-  (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../flutter/SKILL.md`,
-  `../postgresdb/SKILL.md`).
-- Project-wide non-negotiables (stack canon, quality bars) → `../constitution/SKILL.md`.
+| Writing the real code in the plan "because it's faster" | You dropped an altitude. Syntax is the stack skill's job at `implement`. Pull back to contracts. |
+| Planning around a spec that is "a bit fuzzy but I get the gist" | A plan on an unclarified spec is a guess. STOP, route to `clarify`, then plan. |
+| Testing strategy = "we'll write tests" | Not a strategy. Name the level per acceptance criterion and what each test fakes. |
+| Keeping risks short because they read negative | The plan that claims no risk is the riskiest. Rank the real ones, give each a mitigation. |
+| Picking the framework, ORM and config here | Stack canon lives in the constitution; mechanics live in the stack skill. Stay above the seam. |
+| Listing two designs and letting the reader choose | Decide. Alternatives ship only with a trade-off and a recommendation matched to the constitution. |
+| One big undifferentiated sequencing step | Then `tasks` cannot slice it and nothing is independently verifiable. Order it into checkable steps. |
+| Starting a fresh plan when one exists for the slug | Forked plans rot and later phases read the wrong one. Update in place, note the change. |
 
 ## 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:
+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:
 
 > *"Antes de implementar, ¿aíslo este trabajo en un worktree/rama propia (`../worktrees/SKILL.md`)
 > para no tocar tu rama actual? (recomendado)"*
 
-Propose it here at the plan→build boundary so the decision is made before `implement` writes a line.
-If the user accepts, hand to `../worktrees/SKILL.md` first; if they decline, note it and continue.
-If you are already on the default branch (`main`/`master`), isolation is **not** optional — say so
-and route to `worktrees` regardless. (`implement` re-checks this as a hard gate before its first commit.)
+Accepted → hand to `../worktrees/SKILL.md` first. Declined → note it and continue. Already on the
+default branch (`main`/`master`) → isolation is **not** optional: say so and route to `worktrees`
+regardless. (`implement` re-checks this as a hard gate before its first commit.)
+
+## When NOT to use
+
+- Fuzzy idea, no spec yet → `../specify/SKILL.md`; ambiguity in an existing spec →
+  `../clarify/SKILL.md`; project-wide non-negotiables → `../constitution/SKILL.md`.
+- Slicing an approved plan into an ordered checklist → `../tasks/SKILL.md`.
+- Concrete framework/ORM/test-runner mechanics → the stack skill (`../fastapi/SKILL.md`,
+  `../nextjs/SKILL.md`, `../go/SKILL.md`, `../flutter/SKILL.md`, `../postgresdb/SKILL.md`).
 
 ## Next in the chain
 
 Plan written, indexed, decisions logged → propose isolation (above), then hand off to
-**`../tasks/SKILL.md`**, which turns the sequencing section into an ordered, independently-verifiable
-task list with a done-check per task. If planning surfaced an ambiguity the spec never resolved,
-loop back to **`../clarify/SKILL.md`** before tasking.
+**`../tasks/SKILL.md`**, which turns §6 into an ordered task list with a done-check per task. If
+planning surfaced an ambiguity the spec never resolved, loop back to **`../clarify/SKILL.md`** first.