@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/prompts/review-rubric.md

@@ -1,91 +1,64 @@
 # Code Review Rubric
 
-This document is the **rubric the reviewer applies**: how a finding earns its severity, the output
-format for each round, the nine categories that must all be checked, and the conditions that stop a
-review. It is handed to `/code-review` by `pnpm josh review:brief`, which prints its absolute path
-and instructs the review to read and apply it — `/code-review` runs in a forked process that reads
-none of this repository's other documents, so this file has to stand on its own.
-
-The orchestration around a review — when it runs, which round is due, how the gate runs beside it,
-when the pull request opens — is not here; it lives in `prompts/review.md` and the
-`workflow-commands` skill, and the run has already resolved it into the brief. This file is only what
-the reviewer needs to read the diff.
-
-**Default hypothesis: this diff contains at least one non-trivial issue.** Your job is not to confirm
-the implementation is correct — it is to find the issue. Work through each category assuming the code
-is wrong until you can prove otherwise. Do not declare a category clean unless you have actively
-tried to break it.
-
-**In the second round that hypothesis is aimed at the fix delta, not at the whole diff again.**
-Applied twice to one diff it returns new findings whether or not the code changed, because returning
-none is what it rules out — see "The second round is a verification pass" below.
+The rubric the reviewer applies: severity, output format, the nine categories and stop conditions.
+`pnpm josh review:brief` prints its absolute path for `/code-review`, which runs in a forked process
+reading no other repository document, so this file stands alone. Orchestration (when a review runs,
+which round is due, the gate, the PR) is in `prompts/review.md` and the `workflow-commands` skill,
+already resolved into the brief.
+
+**Default hypothesis: this diff contains at least one non-trivial issue.** Your job is to find it, not
+to confirm correctness. Assume each category is wrong until proven otherwise; declare one clean only
+after actively trying to break it. In the second round the hypothesis is aimed at the fix delta, not
+the whole diff (see "The second round is a verification pass" below).
 
 ---
 
 ## Severity (decided by a test, never by discretion)
 
-The output format below demands a severity on every finding. `medium` is a blocker — it must be
-fixed before the PR is opened — so a borderline finding rated `medium` costs a whole round, and
-whether it got one must not be left to whoever happened to be reviewing.
+`medium` blocks opening the PR, so a borderline `medium` costs a whole round — decide it by test.
 
 **A finding is `medium` or higher only when both of these hold:**
 
-1. **It reaches something real** — a runtime code path, a distributed artifact a consumer reads, **or
-   the verification that guards either**: a test, fixture or CI check whose defect lets one of the
-   first two ship unnoticed. The third member is not decoration. `package.json` excludes
-   `**/*.test.ts` and `**/*-fixture.ts` from what it ships, so without it a vacuous or wrongly-pinned
-   suite — the failure mode this repository's marker suites exist to prevent — could never exceed
-   `low` and would always be skippable in one line.
+1. **It reaches something real** — a runtime code path, a distributed artifact a consumer reads, or
+   the verification that guards either (a test, fixture or CI check whose defect lets one of the first
+   two ship unnoticed). `package.json` does not ship `**/*.test.ts` or `**/*-fixture.ts`, so without
+   this third member a vacuous or wrongly-pinned suite could never exceed `low`.
 2. **You can write the concrete failure scenario** — the inputs or state, and the wrong output,
    breakage or misreading that follows. Not "this could be confusing": the actual sequence.
 
-**Fail either test and the finding is `low`.** In particular, **a finding whose failure scenario you
-cannot write is `low` however uncomfortable it looks** — that is the whole of the second test, and it
-is the one that decides borderline cases.
-
-**Test 2 asks whether a scenario can be written, not whether you wrote one.** The cheap action — not
-attempting it — produces the non-blocking severity. So the obligation is to **attempt the scenario
-for every finding that passes test 1, and to say so when the attempt failed**: "no failure scenario —
-<what you tried>" is the evidence, and a `low` on a test-1 finding without it is not a severity, it
-is a skipped step.
+Fail either test and the finding is `low` — **a finding whose failure scenario you cannot write is
+`low` however uncomfortable it looks**.
 
-**A distributed artifact is on that list deliberately.** `CLAUDE.md`, `prompts/**`, `.claude/**` and
-`docs/**` are reviewed at the same level as runtime code — a dangling pointer or a citation naming the
-wrong file reaches every consumer, and no test covers prose.
+Test 2 asks whether a scenario can be written, not whether you wrote one: attempt it for every finding
+that passes test 1, and when the attempt fails write "no failure scenario — <what you tried>". A `low`
+on a test-1 finding without that line is a skipped step.
 
-**`high` and `low`.** A `high` is fixed before committing and blocks the merge regardless of round
-count; a `low` that does not reach the user may be skipped with a one-line reason. This section
-decides which findings reach `medium`, not what a severity then does.
+Distributed artifacts — `CLAUDE.md`, `prompts/**`, `.claude/**`, `docs/**` — are reviewed at the same
+level as runtime code: a dangling pointer or a citation naming the wrong file reaches every consumer,
+and no test covers prose.
 
-**A `low` is not automatically droppable.** A finding that passed test 1 and was rated `low` only for
-want of a failure scenario still reaches the user, so where it closes in a few lines inside a file
-the diff already touches it is fixed rather than dropped. A `low` that fails test 1 — one that does
-not reach the user — is the droppable kind.
+`high` is fixed before committing and blocks the merge regardless of round count. A `low` that fails
+test 1 (does not reach the user) may be dropped with a one-line reason; a `low` that passed test 1 and
+lacks only a failure scenario still reaches the user, so if it closes in a few lines inside a file the
+diff already touches, fix it.
 
 ---
 
 ## The second round is a verification pass, not a second full review
 
-**The second round asks a different question from the first.** Read one diff twice under the
-"assume it is wrong" instruction and the two readings return different findings whether or not the
-code changed, because returning none is what the instruction rules out. So a Medium would stand at
-the second round even where the fixes were sufficient. The second round is narrowed to remove that.
-
-**What changes is the question, never the standard.** A confirmed High still blocks the merge
-whatever the round count, the cap in `prompts/review.md` → "Review round cap" still holds, and every rule here applies to this pass
-unchanged.
+Read twice under "assume it is wrong", one diff returns new findings whether or not the code changed,
+so round 2 asks a different question. **The question changes, never the standard**: a confirmed High
+still blocks the merge, the cap in `prompts/review.md` → "Review round cap" still holds, and every rule
+here applies unchanged.
 
-|                | The first round      | The second round                                                                                                                                                               |
-| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Scope**      | the whole change     | the **fix delta**: what the first round's fixes wrote, plus the call sites of any signature they changed                                                                       |
-| **Question**   | "review this change" | "did each first-round finding actually close, and did the fix itself introduce a defect?"                                                                                      |
-| **Categories** | all nine             | category 1 (Bug risks & logic errors), plus the categories the fix delta actually touches — i18n only if a fix added a user-visible string, Tests only if a fix changed a test |
-| **Output**     | the full template    | one line per first-round finding with its resolution, then any new finding **inside the fix delta**                                                                            |
+|                | First round          | Second round                                                                                                          |
+| -------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Scope**      | the whole change     | the fix delta: what round 1's fixes wrote, plus call sites of any signature they changed                              |
+| **Question**   | "review this change" | "did each first-round finding close, and did the fix introduce a defect?"                                             |
+| **Categories** | all nine             | category 1, plus categories the fix delta touches (i18n only for an added user-visible string, Tests only for a test) |
+| **Output**     | the full template    | one line per first-round finding with its resolution, then new findings inside the fix delta                          |
 
-The brief for round 2 names the exact files that are in scope. Do not re-read the parts of the diff
-no fix touched.
-
-Template for the second round:
+The round-2 brief names the in-scope files; do not re-read parts no fix touched.
 
 ```md
 ### First-round findings
@@ -102,35 +75,27 @@ Template for the second round:
 <counts by severity across both sections, and overall go/no-go>
 ```
 
-**A first-round finding the fix did not close is still a finding, at its original severity.** The
-pass narrows what is read, not what counts — an unresolved High blocks exactly as it did in the first
-round.
+An unclosed first-round finding keeps its original severity; an unresolved High blocks as before.
 
 ---
 
 ## Review output format
 
-Output every category below with an explicit verdict. Do **not** omit categories.
-
-**This is the first round's format.** The second round is a verification pass and has its own,
-narrower one — see above.
+First-round format (round 2 uses the one above). Give every category an explicit verdict; omit none.
 
 For each finding:
 
 - Cite `file_path:line_number`
-- State **severity** (`high` / `medium` / `low`) — decided by the two tests in "Severity" above, not
-  by discretion
+- State severity (`high` / `medium` / `low`) by the two tests in "Severity"
 - Explain the concrete problem and the minimal fix
-- On a finding that passes test 1 of "Severity" but is rated `low`, write the attempt: `no failure
-scenario — <what you tried>`
+- On a test-1 finding rated `low`, write `no failure scenario — <what you tried>`
 
-For categories with no findings, you **must** write a brief proof statement — not just `No issues`.
-Example: `No issues — checked null returns on X, verified Y edge case, Z is guarded by type.` A bare
-`No issues` is only acceptable for Security, Performance, i18n, and Comments when there is genuinely
-nothing to check (no auth code, no hot paths, no user strings, no comments touched).
+A category with no findings needs a proof statement, e.g. `No issues — checked null returns on X,
+verified Y edge case, Z is guarded by type.` A bare `No issues` is allowed only for Security,
+Performance, i18n and Comments when there is genuinely nothing to check (no auth code, hot paths, user
+strings or comments touched).
 
-Template — one `###` heading per category, in the order of "Review categories" below, then
-`### Summary`:
+Template — one `###` heading per category in the order of "Review categories", then `### Summary`:
 
 ```md
 ### Bug risks & logic errors
@@ -159,25 +124,23 @@ No issues — `parse_ids` returns what its name says; no near-copy of `split_ids
 
 ## Review categories (must all be checked)
 
-All nine are checked in the first round. **The second round checks category 1 plus the categories its
-fix delta actually touches** — the verification pass above is the only thing that narrows this list.
+Round 1 checks all nine; round 2 checks category 1 plus the categories its fix delta touches.
 
 ### 1. Bug risks & logic errors
 
-Actively try to break the changed code before concluding it is correct.
+Actively try to break the changed code.
 
-- **Off-by-one, nullability, promise handling, race conditions**: for every modified function that
-  has branching logic, trace at least one non-happy-path scenario. Write the trace explicitly:
+- Off-by-one, nullability, promise handling, race conditions: for every modified function with
+  branching, trace at least one non-happy path and write it:
   `Traced [input/state] → [result] — confirmed/flagged because [reason]`.
-- **Broken invariants, wrong return types, mishandled edge cases**
-- **Boundary values and concurrency**: empty / zero / max inputs, unawaited promises, shared state,
+- Broken invariants, wrong return types, mishandled edge cases
+- Boundary values and concurrency: empty / zero / max inputs, unawaited promises, shared state,
   re-entrancy
-- **Impact outside the diff**: for every changed export or signature, open its callers and verify
-  they still hold; flag duplication the change introduces
-- **Regressions**: does the change break any existing behavior covered elsewhere?
+- Impact outside the diff: open the callers of every changed export or signature and verify they still
+  hold; flag duplication the change introduces
+- Regressions in existing behavior covered elsewhere
 
-`No issues` requires at least one explicit trace statement. Stating `No issues` without a trace is not
-allowed.
+**`No issues` requires at least one explicit trace statement.**
 
 ### 2. Security
 
@@ -189,67 +152,59 @@ allowed.
 
 - Obvious hotspots, N+1 queries, unnecessary re-renders / reactive churn
 - Large payloads, unbounded loops, blocking I/O on request paths
-- Avoid speculative micro-optimization — flag only concrete impact
+- Flag only concrete impact, not speculative micro-optimization
 
 ### 4. Project conventions (`CLAUDE.md`)
 
-**Do not re-check what lint enforces — the gate has already run; lint does not catch duplication
-that is not identical, a name whose shape passes but whose meaning misleads, grouping and file layout,
-Svelte semantics, or test placement beyond the `*.spec.*` / top-level `tests/` bans, so check those.**
-A lint gap the change opens — a disabled rule, an ignored path, an added `eslint-disable`, a block
-switching `no-restricted-syntax` off — is itself a finding.
+Do not re-check what lint enforces (the gate already ran). Check what lint misses: non-identical
+duplication, a name whose shape passes but whose meaning misleads, grouping and file layout, Svelte
+semantics, and test placement beyond the `*.spec.*` / top-level `tests/` bans. **A lint gap the change
+opens is itself a finding** — a disabled rule, an ignored path, an added `eslint-disable`, a block
+switching `no-restricted-syntax` off.
 
 ### 5. i18n
 
 - All user-visible strings (labels, buttons, toasts, validation errors, page titles) use message keys
-- Message keys are added to **all** locale message files, not just one
-- No hardcoded user-visible strings slipped in
+- Message keys are added to all locale message files, not just one
+- No hardcoded user-visible strings
 
 ### 6. Tests
 
 - Every code change has a corresponding test (unit or E2E) per `CLAUDE.md` Code Change Rules Step 0
-- Test titles are English only
-- Test names describe behavior, not implementation
-- **Mutation check**: for the most critical test added or changed, ask: "If I inverted or removed the
-  key assertion/condition in the implementation, would this test fail?" If the answer is no or
-  uncertain, the test does not verify the behavior — rewrite it.
-- **Requirement check**: does the test verify the behavior described in the issue/task, or just that
-  code executes without error?
+- Test titles are English only and describe behavior, not implementation
+- **Mutation check**: for the most critical test added or changed — if the key assertion/condition in
+  the implementation were inverted or removed, would it fail? If no or uncertain, rewrite it.
+- **Requirement check**: does the test verify the behavior the issue/task describes, or only that code
+  runs without error?
 
 ### 7. Comments & content
 
 - Comments are English only
-- No narration comments (`// Added for issue #123`, `// TODO: refactor later`) — only comments
-  explaining non-obvious _why_
+- No narration comments (`// Added for issue #123`, `// TODO: refactor later`) — only non-obvious _why_
 - No duplicated logic that should be extracted
 
 ### 8. Assumptions audit
 
-List 2–3 implicit assumptions the implementation makes. For each, state what would break if the
-assumption were violated. This section cannot be empty or say "No assumptions."
-
-Examples of assumptions worth naming:
+List 2–3 implicit assumptions and what breaks if each is violated. Never empty or "No assumptions."
 
-- "The API always returns an array (not null)" — would break with a null-ref if the API changes
-- "The locale file always has this key" — would silently show a key string if a locale is missing
-- "The animation completes before the next interaction" — race condition if the user acts fast
+- "The API always returns an array (not null)" — null-ref if the API changes
+- "The locale file always has this key" — shows a key string if a locale is missing
+- "The animation completes before the next interaction" — race if the user acts fast
 
 ### 9. Confidence floor
 
-State the **one concrete thing** in this change you are least confident about, and explain why. This
-section cannot say "Nothing" or "No concerns." If genuinely nothing is uncertain, trace the exact
-logic path that gives you that confidence — that trace itself is the proof.
+State the **one concrete thing** you are least confident about, and why. Never "Nothing" or "No
+concerns"; if nothing is uncertain, trace the logic path that gives that confidence as the proof.
 
 ---
 
 ## Stop conditions
 
-- **A checkout that cannot be attested** → report `REVIEW TARGET MISMATCH` and **no findings**, and
-  do not report a verdict of any kind. `pnpm josh review:attest <nonce>` exiting non-zero means this
-  review read a tree the brief did not describe, so everything it would say — "no findings" above all
-  — is about somebody else's code.
-- **High** findings → must fix before committing
-- **Medium** findings → must fix before opening the PR
-- **Low** findings → document in the PR body if skipped
+- **A checkout that cannot be attested** (`pnpm josh review:attest <nonce>` exits non-zero) → report
+  `REVIEW TARGET MISMATCH`, no findings and no verdict of any kind: the review read a tree the brief did
+  not describe.
+- High findings → must fix before committing
+- Medium findings → must fix before opening the PR
+- Low findings → document in the PR body if skipped
 
-If the diff is empty or trivial (e.g. whitespace only), state that explicitly and skip the review.
+If the diff is empty or trivial (e.g. whitespace only), state that and skip the review.