devrites 1.19.0

package/pack/.claude/skills/rite-resolve/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: rite-resolve
+description: Resolve open `questions.md` entries on the active feature — answer one, drop one, or batch-resolve from a file — and clear `state.md` `Awaiting human` so the workflow resumes. Use when the user says "answer that question", "drop that question", or a HITL checkpoint / AFK blocking question needs an answer. Not for raising new questions or editing answered ones.
+argument-hint: "<qid> \"<answer>\"  |  --drop <qid> [\"<reason>\"]  |  --batch <path-to-yaml>"
+user-invocable: true
+---
+
+# /rite-resolve — answer the human gate
+
+`/rite-resolve` is the canonical resume verb for **async** human gates — a checkpoint that
+already paused and **stopped the session** (an AFK blocking/escalating/irreversible queue, or a
+HITL pause the human walked away from), plus `--batch`. When `/rite-build` asks a gap **inline**
+via `AskUserQuestion` and the human is present, that pick resolves the gate **in place** through
+the same `resolve.sh` writer — you don't type `/rite-resolve` for it. For the async case this
+skill takes the human's answer (or `--drop` / `--batch`), writes it to `questions.md`, updates
+`state.md` (clears `Awaiting human`, sets `Status: running`), and recommends the next command.
+
+It is **deliberately small**: one verb, one source of truth (`questions.md`), one cursor
+(`state.md`). The full AFK / HITL contract lives in
+[`afk-hitl.md`](../../rules/afk-hitl.md).
+
+## Rules consulted (read on demand from `.claude/rules/`)
+
+Read `.claude/rules/core.md` first. Then pull these via `Read` when shaping the resolve:
+
+- `afk-hitl.md` — gate taxonomy, `questions.md` schema, AFK exception rules.
+- `documentation.md` — record decisions and rationale where the answer changes scope.
+
+## Operating rules
+
+- **Requires an active workspace.** Read `.devrites/ACTIVE` first; if empty or the slug
+  has no `questions.md`, **STOP** and tell the user to run `/rite-spec <feature>` first.
+- **One mutation per call.** A single qid (or `--batch` file) per invocation; never
+  silently coalesce multiple human decisions into one log entry.
+- **Never overwrite an answered question.** If the qid's `status` is `answered` or
+  `dropped`, refuse with the existing answer; ask the user to open a new qid that
+  references the old one (the file is the audit trail).
+- **If the answer materially changes scope, architecture, or acceptance**, route it
+  through the Spec Drift Guard (`/rite-plan repair`) **after** writing the answer — do
+  not modify `spec.md` / `plan.md` inside this skill.
+- **The script is the source of truth.** Always invoke
+  `devrites-lib/scripts/resolve.sh` — it keeps `questions.md` + `state.md` consistent and emits the
+  next-action recommendation. The one `state.md` field this skill may write by hand is the
+  unblocked slice's `Slice mode` (step 4, the named exception); everything else goes through
+  the script, never by hand.
+- **Human gates are for human-only decisions, not the agent's work.** A `questions.md` entry the
+  human must answer is a genuine *decision* (a scope / design / risk call only the human can make)
+  — not a task the agent can do itself. If a question is really agent-doable ("should I write the
+  test?", "go implement X"), don't record a human answer that punts the agent's own job back to it:
+  flag the mis-tag and route it to the right skill (`/rite-build`, `/rite-plan unblock`,
+  `devrites-debug-recovery`). The human resolves decisions; the agent does the work.
+
+## Workflow
+
+0. **Read `.claude/rules/core.md`** (operating rules + persistence discipline) before
+   touching the workspace.
+   Then **run the shared orientation preamble** — it prints `state.md`, the artifacts present,
+   the run mode (HITL/AFK), and the open-question tally by gate, so you orient deterministically
+   instead of re-deriving state from raw Markdown:
+   ```bash
+   P=.claude/skills/devrites-lib/scripts/preamble.sh
+   [ -f "$P" ] || P="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/preamble.sh"
+   [ -f "$P" ] || P=pack/.claude/skills/devrites-lib/scripts/preamble.sh
+   [ -f "$P" ] && bash "$P" || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
+   ```
+1. **Parse arguments.** `$ARGUMENTS` is one of:
+   - `<qid> "<answer>"` — answer the single open question.
+   - `--drop <qid>` (optional `"<reason>"`) — mark the question `dropped`; record
+     the reason inline.
+   - `--batch <path-to-yaml>` — bulk resolve, one entry per qid (see
+     [`reference/answer-protocol.md`](reference/answer-protocol.md) for the batch
+     format).
+2. **Load context.** Read `state.md`, `questions.md`, and the relevant slice from
+   `tasks.md`. Confirm the qid is `status: open`. If `state.md` `Status` is not
+   `awaiting_human` and the question's `gate` is `blocking`, surface the inconsistency
+   before proceeding (don't auto-repair — flag it).
+3. **Render preview.** Echo the qid, the question, the proposed answer (if any), the
+   user's answer, and which slice unblocks. Stop here and ask `confirm? (y/N)` **unless**
+   the answer was provided non-interactively via `--batch`.
+4. **Mutate.** Run `bash .claude/skills/devrites-lib/scripts/resolve.sh` with the same
+   arguments. The script:
+   - flips the qid's `status` to `answered` / `dropped` and stamps `answered_at` + `answer`;
+   - if the qid is in `state.md`'s `Awaiting human` block (single-question pause), clears
+     that block and sets `Status: running`;
+   - appends a `Log` line to `state.md`.
+
+   On resume, also clear or update the unblocked slice's `Slice mode` in `state.md`: if
+   the answer lets the slice proceed, drop the pause-time `Slice mode` so `/rite-build`
+   re-derives it on the next selection; if the answer re-shapes how the slice should be
+   built, set `Slice mode` to match.
+5. **Post-resolve hand-off.** If the answer changes product behavior or acceptance →
+   recommend `/rite-plan repair`. Otherwise → recommend the slice's natural next action
+   (typically `/rite-build` for the slice that was awaiting).
+6. **STOP.** This skill does not run `/rite-build` itself — the user re-enters the
+   workflow explicitly.
+
+> **Mid-flight discipline.** Don't edit `spec.md` / `plan.md` to "incorporate" the
+> answer — that's `/rite-plan repair`. Don't silently retry a build after the answer
+> lands — the user types the next command. Don't merge two open questions into one
+> answered entry — each question is independently auditable.
+
+## Output
+
+**Footer first** — render the slice meter + flow ribbon by running the progress footer (`progress.sh`, resolved like the step-0 preamble — canonical snippet in `devrites-lib/SKILL.md`); keep the fact lines below it terse (`key value · key value`). Then:
+```
+Resolved: <qid> (<gate>, slice <N>)
+Answer:   <one-line summary>
+Workspace updates:
+  - questions.md: q-... status open → answered
+  - state.md:     Awaiting human cleared; Status running
+Next: <recommended command — usually /rite-build or /rite-plan repair>
+↻ Hygiene: no /clear needed (read-only on code; the answer is now persisted).
+```

package/pack/.claude/skills/rite-resolve/reference/answer-protocol.md

@@ -0,0 +1,114 @@
+# Answer protocol — how `/rite-resolve` mutates the workspace
+
+`/rite-resolve` is the single canonical writer for `questions.md` `status` flips and
+`state.md` `Awaiting human` clearance. This file is the reference for the three input
+shapes, the batch file format, and the rules the underlying `devrites-lib/scripts/resolve.sh` obeys.
+
+## Three input shapes
+
+### 1. Single answer
+
+```
+/rite-resolve q-2026-05-28-001 "composite index — single key is fine for now, revisit at 1M rows"
+```
+
+- The qid must be `status: open`. Re-answering is refused (see "Never overwrite").
+- The answer is recorded verbatim. Use straight quotes around the answer so the shell
+  preserves whitespace.
+
+### 2. Drop
+
+```
+/rite-resolve --drop q-2026-05-28-002 "merged into q-...-003 after we narrowed the scope"
+```
+
+- A drop is **not** an answer — it removes the question from the active queue without
+  recording a decision. Use it when the question is obsolete, a duplicate, or absorbed
+  by a re-plan.
+- The reason is required as a single trailing string. "obsolete" / "duplicate" /
+  "absorbed by Slice N" are sufficient — but never blank.
+
+### 3. Batch
+
+```
+/rite-resolve --batch .devrites/work/<slug>/answers.batch
+```
+
+The batch file is plain text, one resolution per line. Two line shapes:
+
+```
+q-2026-05-28-001: composite index, revisit at 1M rows
+q-2026-05-28-002: clinician sign-off required at runtime, not at plan time
+--drop q-2026-05-28-003: merged into q-...-004
+# Lines starting with # are comments. Blank lines ignored.
+```
+
+- One qid per line. The first colon is the separator; the rest of the line is the value.
+- Order matters only for `state.md` clearance — the script processes top-to-bottom and
+  flushes `Awaiting human` after each match.
+- Errors abort the batch at the first failing line so partial state is small and
+  diagnosable. (Re-run after fixing the offending line; already-applied lines refuse to
+  re-apply because their `status` is no longer `open`.)
+
+## Never overwrite
+
+A qid that is already `answered` or `dropped` refuses to be re-resolved. The audit trail
+is the file — you do not edit history. If the original answer was wrong:
+
+1. Open a new qid (the agent will, during the next `/rite-build` if the bad answer
+   re-surfaces; or you write it manually).
+2. Reference the old qid in the new question's body (`supersedes: q-...-001`).
+3. Resolve the new qid.
+
+The same rule applies to `--drop`: a dropped question is not undropped. Re-raise it as
+a new qid if it turns out to matter after all.
+
+## State machine
+
+```
+open ──answer──▶ answered  (terminal)
+ │
+ └──drop────▶ dropped   (terminal)
+```
+
+Both terminals stamp `answered_at: <iso>` and write the answer/reason to `answer:`.
+
+## `state.md` clearance rules
+
+`state.md`'s `Awaiting human` block is **single-question by default** — `/rite-build`
+writes one block at a time and pauses. When `/rite-resolve` matches the block's qid:
+
+- the entire `Awaiting human` block is removed (header + fields);
+- `- Status: running` is set;
+- a `Log` line is appended: `- <iso> build: resolved <qid>`.
+
+If `state.md`'s `Status` is `awaiting_human` but no `Awaiting human` block matches the
+qid (drift between the two files), `/rite-resolve` flags the inconsistency and refuses
+to silently fix it. Use `/rite-plan repair` to reconcile.
+
+If the answer materially changes spec/plan, **do not** edit `spec.md` or `plan.md` inside
+`/rite-resolve` — that's `/rite-plan repair`'s job. The skill's post-resolve hand-off
+recommends `/rite-plan repair` whenever the answer touches acceptance criteria, scope,
+or architecture.
+
+## Multi-question awaiting
+
+If a future evolution lets `/rite-build` queue multiple questions per pause, the
+`Awaiting human` block becomes a YAML list. `/rite-resolve` will:
+
+- match the qid in the list and remove only that entry;
+- leave the rest of the list intact;
+- flip `Status: running` only when the list is empty.
+
+This shape is reserved — current `/rite-build` writes one question per pause.
+
+## Why no auto-`/rite-build` after resolve
+
+The user types the next command explicitly. Reasons:
+
+1. The answer may need a `/rite-plan repair` first; auto-continuing would build against
+   a stale plan.
+2. The user may want to `/rite-status` before resuming.
+3. Atomicity: one verb, one mutation. Chaining is a hidden side-effect that hides bugs.
+
+The output's `Next:` line is a recommendation, not an auto-run.

package/pack/.claude/skills/rite-review/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: rite-review
+description: Feature-scoped multi-axis review of the polished diff — Spec + Code-review axes fan out as parallel subagents; findings under one severity scale. Use when the user says "review this", "audit my diff", "final review before seal", "check this against the spec". Not for whole-project refactors or single-slice review.
+argument-hint: "[scope: slice N | feature]"
+user-invocable: true
+---
+
+# /rite-review — feature-scoped review
+
+Senior review of the **active feature scope only**. **Read the active workspace first**;
+if none, tell the user to run `/rite-spec <feature>`.
+
+> **Differs from built-in `/code-review` in:** `/code-review` is a generic
+> diff review with no workspace context. `/rite-review` reads
+> `.devrites/work/<slug>/spec.md` first, runs Spec ↔ Code-review axes as
+> parallel subagents (see [`reference/parallel-dispatch.md`](reference/parallel-dispatch.md)), and gates feeding
+> into `/rite-seal`. Use `/code-review` for a one-off diff; use
+> `/rite-review` for a DevRites feature where the spec is the contract.
+
+## Rules consulted (read on demand from `.claude/rules/`)
+**Step 0:** Read `.claude/rules/core.md` first. The other rule files load on demand;
+pull these via `Read` when the diff demands them:
+- `code-review.md` — small PRs, severity labels, tests-first review focus.
+- `testing.md` — confirm the tests prove the spec, not just pass.
+- `agents.md` — when to fan out to which review subagent.
+- `security.md` — when input / auth / data / integrations / secrets are in scope.
+- `performance.md` — only when perf is relevant or a regression risk is visible.
+
+## Operating rules
+- **Feature scope only.** Review touched files + the diff. **NO whole-project refactors,
+  NO drive-by cleanup.** DO NOT delete suspected dead code outside this feature without
+  asking. Spec Drift Guard applies.
+- **Reviews the finished product.** `/rite-polish` has already done **code simplification**
+  + UI normalize/polish. Review judges; if it reveals a real complexity issue polish
+  missed, flag it as a finding — don't re-run a simplification sweep here.
+- Findings are labeled (below). Re-prove after any change you make.
+
+## Workflow
+0. Read `.claude/rules/core.md` first (the always-on operating rules); pull the
+   on-demand rules above as the diff demands them.
+   Then **run the shared orientation preamble** — it prints `state.md`, the artifacts present,
+   the run mode (HITL/AFK), and the open-question tally by gate, so you orient deterministically
+   instead of re-deriving state from raw Markdown:
+   ```bash
+   P=.claude/skills/devrites-lib/scripts/preamble.sh
+   [ -f "$P" ] || P="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/preamble.sh"
+   [ -f "$P" ] || P=pack/.claude/skills/devrites-lib/scripts/preamble.sh
+   [ -f "$P" ] && bash "$P" || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
+   ```
+1. Read `spec.md`, `tasks.md`, `state.md`, `decisions.md`, `evidence.md`,
+   `touched-files.md`, and the `git diff`. For "what would this change break"
+   questions, prefer a code-intelligence index if available — codebase-memory-mcp first,
+   cross-checked with codegraph + graphify, else standard methods (LSP / Read/Grep/Glob); see
+   `.claude/rules/tooling.md` — over file reads;
+   they answer impact/callers in one call. When a finding hinges on an external library's
+   current API, context7 if available can confirm the signature.
+2. **Review tests first** — do they actually prove the acceptance criteria? Missing,
+   weak, or wrong tests are the first findings.
+3. **Spec ↔ Code-review split (parallel sub-agents, fresh context).** A change can pass
+   one axis and fail the other — code that follows every project standard but
+   implements the wrong thing (Code-review pass, Spec fail), or code that does exactly
+   what the spec asked but breaks project conventions (Spec pass, Code-review fail).
+   Running them serially in one context lets one mask the other. So:
+   - Dispatch **two** read-only reviewers in **parallel** via the `Task` tool, each
+     with its own narrow brief and no cross-pollination:
+     - **Spec axis** → `devrites-spec-reviewer`: "Apply your documented discipline on
+       the active feature workspace + diff. Report (a) criteria the spec asked for that
+       are missing or partial, (b) behaviour in the diff the spec did not ask for
+       (scope creep / drift), (c) criteria implemented incorrectly. Quote the spec
+       line per finding."
+     - **Code-review axis** → `devrites-code-reviewer`: "Apply your full documented
+       discipline (tests-first, correctness, readability, architecture, maintainability,
+       standards) on the active feature workspace + diff. Cite file:line per finding;
+       skip what tooling already enforces. Also flag the AI-codegen smells (silent/empty
+       catch, defensive try-catch bloat + redundant logging, single-use factory / needless
+       indirection, dependency creep where an in-repo option exists, a 100-line function
+       where 20 would do) and the silent-failure bugs (a missing value coerced to 0/''/[],
+       a dropped Result/err return, off-by-one / boundary, logic that contradicts the
+       comment/docstring/name). Per hunk, check whether working code was deleted that the
+       task did not ask to remove."
+   - **Do NOT merge or re-rank** their findings. Present them under separate
+     `## Spec` and `## Code review` sub-sections in `review.md`. Surface contradictions
+     between the axes explicitly (e.g. "Spec axis says complete, Code-review axis says
+     untestable") — `/rite-seal` decides what blocks.
+4. **Reconcile, don't re-review.** With the two parallel reports in hand, the inline
+   lead reconciles — it does **not** re-run a five-axis pass over correctness /
+   readability / architecture / maintainability that `devrites-code-reviewer` already
+   covered. Stay in scope ([feature-scoped-review](reference/feature-scoped-review.md)).
+   Add only what the dispatched agents could not, then resolve overlaps and
+   contradictions before labeling. ([five-axis-review](reference/five-axis-review.md)
+   documents the axes the code-review agent applies.)
+   - **UI feature?** Apply the **UX rubric**
+     ([nielsen-heuristics](reference/nielsen-heuristics.md)) and the
+     **cognitive-load lens** ([cognitive-load](reference/cognitive-load.md)) on the
+     UX axis — surface heuristics scoring ≤ 2 and any cognitive-load findings
+     (extraneous noise, missing progressive disclosure, vocabulary drift) at the
+     appropriate severity.
+5. **Security** — apply `devrites-audit security`
+   ([security-review](reference/security-review.md)) when user input, auth, data
+   storage, external integrations, secrets, or permissions are involved.
+6. **Performance** — apply `devrites-audit perf`
+   ([performance-review](reference/performance-review.md)) only when performance is
+   relevant or a regression risk is visible (measure first).
+7. Apply only in-scope fixes; **run verification after changes** (`/rite-prove` logic).
+8. Update `review.md`, `evidence.md`, and `state.md`.
+
+## Finding labels
+- **Critical** — must fix before seal (correctness/security/data loss).
+- **Important** — should fix before seal (likely bug, real maintainability risk).
+- **Suggestion** — worth doing, not blocking.
+- **Nit** — trivial/style.
+- **FYI** — context, no action implied.
+
+**Action decoration (orthogonal to severity).** Also tag each finding with how to act on it:
+`blocking` (fix before seal), `non-blocking` (fix when convenient), or `if-minor` (fix only if the
+change is already small — a pure noise-economics lever). Only a **`blocking` Critical** gates the
+seal; a `non-blocking` / `if-minor` finding is recorded, not a stop.
+
+## Confidence + signal-to-noise
+Borrow `/rite-vet`'s discipline so review stays **trusted, not noisy** — a reviewer that posts
+18 comments per PR teaches the team to ignore every one (below ~10% false-positive rate devs
+investigate each finding; past ~30% they label the tool noisy and skip it):
+- **Confidence-band each finding** (1–10) and state the band. A low-confidence finding (≤4)
+  you can't verify against the code is **suppressed** — roll it into one `Suppressed
+  (low-confidence): n` line, never raised as Critical/Important.
+- **Verify before you escalate.** Every Critical/Important quotes the spec line or cites the
+  `file:line` that proves it — no unverified blockers.
+- **Budget the noise.** Roll up trivia ("N style nits") into a single line; tooling already
+  catches style. Review's job is correctness + spec fidelity, not a lint dump.
+
+## Severity orientation (labels, not score)
+
+After labeling, summarize findings as `Critical / Important / Suggestion / Nit /
+FYI` counts. There is no composite number — `/rite-seal` gates on
+`Critical == 0` and on acceptance + drift. Inventing a number invites gaming;
+the labels do the work.
+
+> **Mid-flight discipline.** When tempted to demote a Critical, hide a finding, fix without re-verification, or wander out of scope — see [`anti-patterns`](reference/anti-patterns.md). Load it the moment you reach for the excuse.
+
+## Output → `review.md`
+
+**Footer first (to chat, not into the report file)** — render the slice meter + flow ribbon by running the progress footer (`progress.sh`, resolved like the step-0 preamble — canonical snippet in `devrites-lib/SKILL.md`). Then write the report:
+```
+Reviewed: <slice N | feature>
+Tests: <adequate? gaps>
+Kept (≤1, specific): <one concrete decision worth protecting from later churn | omit>
+
+## Spec   (from devrites-spec-reviewer sub-agent, verbatim)
+- <quoted spec line> — <missing / partial / wrong / scope-creep> — <where>
+- ...
+
+## Code review   (from devrites-code-reviewer sub-agent, verbatim)
+- <file:line> — <violation / correctness / readability / architecture / maintainability> — <fix>
+- ...
+
+## Cross-axis contradictions (if any)
+- Spec axis: ... | Code-review axis: ... | who decides at seal: ...
+
+Findings (combined, after the parallel pass):
+  [Critical]   <n> — <file:line — problem — fix>
+  [Important]  <n> — <file:line — problem — fix>
+  [Suggestion] <n> — <file:line — problem — fix>
+  [Nit]        <n> — <file:line — problem — fix>
+  [FYI]        <n> — <file:line — note>
+Fixes applied (in scope): ...
+Re-verification: <cmd → pass/fail>
+Re-prove: <if review changed code, run a scoped `/rite-prove` so evidence post-dates the fix | n/a — no code changed>
+Next: /rite-seal   (or fix Criticals first)
+↻ Hygiene: /compact (review findings) if fixing Criticals/Importants this session; /clear if review is clean — see rules/context-hygiene.md.
+```

package/pack/.claude/skills/rite-review/reference/anti-patterns.md

@@ -0,0 +1,32 @@
+# rite-review — anti-patterns
+
+Load this when standing a non-trivial review decision, when tempted to
+demote severity to hide a finding, or when crossing out of feature scope.
+
+Pack-wide rationalizations + red flags: see
+[rules/anti-patterns.md](../../../rules/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "Polish already cleaned this up; nothing to flag." | Polish finishes; review judges. If review still spots a real issue, flag it — don't re-run polish here. |
+| "Tests pass, so they're adequate." | Adequacy = do they prove acceptance, including failure / boundary / empty paths? A passing test is not automatically a good test. |
+| "Security audit isn't needed for this feature." | If the feature touches user input, auth, data storage, external integrations, secrets, or permissions — yes it is. |
+| "I'll just fix everything I find in scope." | Some fixes belong in `/rite-plan` as drift, not as smuggled redesigns inside review. |
+| "Performance is fine without measuring." | No claim without a number or a specified measurement. "Feels fast" is not a finding. |
+
+## Severity gaming
+
+| Excuse | Rebuttal |
+|---|---|
+| "Demoting a Critical to Important keeps the review clean." | Severity reflects the actual risk to ship — not the review you'd like. |
+| "I won't surface this Critical; user can find it later." | Hidden Criticals are the worst-case play. The seal blocks anyway, and now you've burned trust. |
+
+## Red Flags
+
+- A finding without `file:line`.
+- A finding without a severity label (Critical / Important / Suggestion / Nit / FYI).
+- A Critical recorded but silently fixed instead of surfaced to the seal.
+- A fix applied without re-verification afterwards.
+- Review crossing into out-of-scope files because they "looked wrong".

package/pack/.claude/skills/rite-review/reference/cognitive-load.md

@@ -0,0 +1,90 @@
+# Cognitive load — a UX review lens
+
+Cognitive load is the total mental effort the interface demands. Overloaded users
+hesitate, misclick, abandon. Reviewing UI without this lens misses a whole class of
+defects that no a11y checker or perf tool will flag.
+
+DevRites' `/rite-review` uses this reference when the feature touches UI. It is
+descriptive (helps you spot defects) rather than scored — findings raised here
+roll up under the UX axis of the multi-axis review with the usual severity labels.
+
+## Three kinds of load
+
+| Type | Source | Reviewer's job |
+|---|---|---|
+| **Intrinsic** | The task itself — its inherent steps, decisions, and required knowledge. | Can't be eliminated, only **structured**: step the user through it, provide defaults, group related decisions, defer what isn't needed yet. |
+| **Extraneous** | Bad design — friction the task doesn't require: noisy hierarchy, redundant choices, jargon, layout that hides the next step. | **Eliminate it ruthlessly.** It's pure waste, and the easiest class of finding to land. |
+| **Germane** | Effort the user spends *forming a mental model* of the product. | **Invest deliberately.** Consistent flows, shared vocabulary, predictable affordances — anything that lets the user re-use what they already learned. |
+
+A surface can be intrinsic-heavy *and* extraneously-fine — that's a hard task done
+right. A simple surface that still feels heavy is extraneous load disguised as
+"complexity."
+
+## Symptoms reviewers should flag
+
+Treat each as a finding when present; classify by load type so the fix is obvious.
+
+### Extraneous (reduce / remove)
+- **Visual noise** that doesn't earn its place: redundant borders, shadows,
+  dividers, gratuitous icons next to every label, colour used decoratively.
+- **Competing primary actions** — two or three buttons of equal weight when one
+  is clearly the next step.
+- **Jargon and abbreviations** the user doesn't share — names from the codebase
+  or internal team that leaked into the UI.
+- **Restated headings** (the body of a section repeats the section title in
+  long-form).
+- **Decision paralysis** — too many options when one default + a "more options"
+  toggle would do.
+- **Form fields without obvious priority** — required vs optional, primary vs
+  secondary mixed in a single column with no rhythm.
+- **Premature error messaging** (validation that fires before the user has
+  finished typing).
+
+### Intrinsic (structure, don't try to eliminate)
+- **No progressive disclosure** on a genuinely complex task — every field
+  visible at once because "the user might need it".
+- **No safe defaults** on multi-step flows — the user has to choose at every step
+  even when one path is the obvious answer.
+- **Decisions grouped wrong** — "billing address" sandwiched between two
+  unrelated sections rather than next to "shipping address".
+- **No scaffolding** (no template, no example input, no recently-used value)
+  for tasks that have a high blank-page cost.
+
+### Germane (invest in)
+- **Inconsistent vocabulary** across the feature — same concept named two ways
+  (e.g. "member" in one screen, "user" in the next).
+- **Flow-shape divergence** from neighbouring features (modal where the project
+  uses inline; route-change where the project uses an overlay).
+- **Affordances that look interactive but aren't** (and vice versa) — destroys
+  the mental model the user is trying to build.
+
+## Reviewing a flow — three-pass discipline
+
+1. **First pass: silent.** Walk the flow without reading any explainer copy.
+   Anything that stops you cold without copy is a finding — either extraneous
+   load you can't dismiss, or a germane-load problem (the user is missing a
+   mental model the UI assumes).
+2. **Second pass: with copy.** Read every label, helper, and error. Does the
+   copy resolve the friction the first pass surfaced, or just paper over it?
+   "Tooltip explaining a confusing button" is rarely the right fix — usually
+   the button needs a different label.
+3. **Third pass: empty + error.** Run the flow with no data, partial data, and
+   the worst inputs (offline / 500 / permission-denied). Most cognitive-load
+   defects hide in non-happy paths because nobody designs them.
+
+## The cheap-fix test
+
+If a finding would take more than 30 minutes to fix, classify it (token gap /
+component miss / flow misalignment per `rite-polish/reference/ui.md`) and
+route to the appropriate bucket. Cognitive-load review surfaces problems; it
+doesn't decide the rewrite strategy.
+
+## What this lens **doesn't** cover
+
+- **Accessibility** — separate axis (WCAG 2.2; see `quality-standards.md`).
+- **Performance** — separate axis (Core Web Vitals; see `quality-standards.md`).
+- **Code quality** — covered by the simplification audit
+  (`devrites-audit simplify`).
+- **Security** — covered by the security audit (`devrites-audit security`).
+
+Cognitive-load findings live on the **UX axis** of the multi-axis review.

package/pack/.claude/skills/rite-review/reference/feature-scoped-review.md

@@ -0,0 +1,26 @@
+# Feature-scoped review
+
+The review boundary is the **active feature**: the files in `touched-files.md` and the
+current diff. This is a hard rule, not a guideline.
+
+## In scope
+- Code added/changed by this feature.
+- Tests for this feature.
+- Files this feature intentionally inspected and depends on (read for context, but
+  don't refactor them).
+
+## Out of scope (do NOT)
+- Refactor unrelated modules because they're "nearby" or "while we're here".
+- Delete suspected dead code outside this feature without asking the user.
+- Restyle/upgrade dependencies or change project-wide config to suit this feature.
+- Expand the review into a project audit.
+
+## When you spot a real problem outside scope
+Record it as an **[FYI] follow-up** in `review.md` (and suggest a separate feature/issue)
+— don't fix it inline. Drive-by changes balloon the diff, dodge their own review, and
+mix concerns the seal can't cleanly evaluate.
+
+## Why scope discipline matters
+A tight diff gets a real review; a sprawling one gets a rubber stamp. Scope creep is how
+"a small fix" becomes an unreviewable, unprovable change. Keep the feature shippable and
+the review honest.

package/pack/.claude/skills/rite-review/reference/five-axis-review.md

@@ -0,0 +1,46 @@
+# Five-axis review
+
+The axes the dispatched `devrites-code-reviewer` applies to the diff (tests first
+— always), under one severity scale (Critical / Important / Suggestion / Nit / FYI).
+The `/rite-review` inline lead **reconciles** the returned report against the Spec
+axis — it does not re-run these axes itself. This file is the shared definition of
+what "full code-review discipline" covers; use it to judge whether the agent's report
+is complete, and to scope anything the agent could not (e.g. UI-only lenses below).
+
+## 0. Tests (first)
+- Do tests exist for the changed behavior, and do they prove the acceptance criteria?
+- Would they fail if the code were wrong? (No assertion-free or tautological tests.)
+- Edge cases: empty, boundary, error, permission-denied, concurrency.
+
+## 1. Correctness
+- Does it do what the spec says? Off-by-one, null/undefined, error paths, race
+  conditions, incorrect assumptions about inputs.
+- Does it handle the states the slice promised (loading/empty/error for UI)?
+
+## 2. Readability
+- Can the next engineer understand it without the author? Naming, function length,
+  nesting depth, comments that explain *why* not *what*.
+
+## 3. Architecture
+- Right seam/boundary? Coupling and cohesion. Does it fit existing patterns or
+  introduce a competing one? Is the abstraction earned (not premature)?
+
+## 4. Security
+- Trust boundaries, input validation, authz checks, secrets handling. Hand off to
+  `devrites-audit security` when input/auth/data/integration is in scope.
+
+## 5. Performance
+- Obvious N+1s, unnecessary work in hot paths, payload sizes. Hand off to
+  `devrites-audit perf` when perf is relevant — **measure before claiming**.
+
+## 6. Maintainability
+- Tests, docs/comments where needed, no dead code added, no TODOs left, consistent
+  with project conventions.
+
+## Frontend axes (if UI)
+- UX flow matches neighbors; all interaction states; a11y (focus, labels, contrast,
+  keyboard); responsive; design-system alignment (no drift, no anti-AI-slop).
+
+## Sizing & speed
+Prefer reviewing roughly one slice / ~100 lines of meaningful change at a time. Larger
+diffs hide defects — recommend splitting rather than rubber-stamping.