feat: refresh shared skills catalog

skills/review/SKILL.md

@@ -1,88 +1,28 @@
 ---
 name: review
 description: >
-  Adversarial pre-implementation review of SPEC.md. Attempts to refute the spec before code is written,
-  grounding findings in codebase evidence, §R research, and current best practices.
-  Use when asked to "review spec", "red-team spec", "is this plan sound", or before high-blast-radius builds.
-concerns: [system-one-balance]
+  Review an existing SPEC.md before implementation when asked to review or red-team the spec, or when spec review is part of the authorized task.
+scope: global
 ---
 
-# Review — Refute the Spec Before Build
+# Spec review
 
-Every finding cites evidence — `file:line` or an authoritative source. No evidence → label `[unverified]`. A defect you cannot prove is a note, not a blocker.
+1. Read the relevant goals, constraints, interfaces, research, invariants, and tasks.
+   Inspect implementations and callers affected by the proposed change.
+2. Test consequential assumptions against code, existing tests, and current primary
+   sources where needed. Look for mismatched requirements, contract conflicts,
+   missing failure behavior, and tasks without observable completion evidence.
+   For substantial specs, a fresh-context pass can expose assumptions inherited
+   from drafting. When an isolated reviewer is available, give it the spec, relevant
+   source, and review criteria without the drafting conversation. If isolation is
+   unavailable, reread the spec as a standalone document and note that the review
+   shared drafting context. Skip this extra pass for small or straightforward specs.
+3. Report demonstrated defects with file/line or source evidence and concrete remedies.
+   Distinguish material hardening from optional notes; unverified claims stay notes.
+4. Draft useful invariant/interface/task amendments when needed. Do not edit a spec
+   during a report-only review; apply amendments only within an authorized edit.
+5. Give a go/no-go verdict if requested or useful for the pending implementation.
+   A sound spec needs a short conclusion, not fabricated blockers.
 
----
-
-## Phase 0: Setup and Protocols
-
-1. Review governing invariants:
-   - Review the *spec*, not conversational memory.
-   - An LLM cannot self-correct reliably on vibes alone; the reviewer must anchor to external oracles (code, tests, §R).
-   - Skip review for trivial, reversible edits; right-size review effort to blast radius.
-
----
-
-## Phase 1: Ingest and Check
-
-1. **Capture the Spec**:
-   - Ingest all active sections of `SPEC.md`: §G, §C, §I, §R, §V, §T, §B.
-2. **Construct the Reviewer Profile**:
-   - Inspect the codebase modules touched by the spec to verify existing patterns and constraints.
-   - Check §R research findings: any spec assertion contradicting §R is an immediate finding.
-   - For unverified best-practice assumptions, verify them before citing.
-
----
-
-## Phase 2: Processing (Core Logic)
-
-### Step 1: Adversarial Refutation
-Attempt to refute the spec along these axes:
-- **Goal vs. Reality**: Does §G address the actual requirement or a proxy?
-- **Missing Invariants**: What failure mode exists that no §V catches?
-- **Interface Drift**: Does §I match what existing callers in the codebase expect? Cite caller `file:line`.
-- **Constraint Conflicts**: Do two bullets in §C contradict each other or violate §R?
-- **Unowned Edges**: What concurrency, ordering, or failure scenario has no assigned §T?
-- **Altitude Check**: Are tasks in §T too vague to verify, or overly granular?
-
-### Step 2: Classify Findings
-Assign findings to three explicit categories:
-- **BLOCK**: High risk of shipping a real defect. Must be resolved before building.
-- **HARDEN**: Add or sharpen a §V invariant so build cannot regress it.
-- **NOTE**: Worth noting for future consideration; non-blocking.
-
-*Any claim lacking codebase or documentation evidence is down-ranked to NOTE and tagged `[unverified]`.*
-
-### Step 3: Draft §V Amendments
-- Translate each HARDEN finding into a testable §V draft line citing the interface or behavior guarded.
-
----
-
-## Phase 3: The System One Balance Pass
-
-- **Augment, Don't Handcuff**:
-  - Never review trivia or low-risk tasks (typos, minor styling, internal helper adjustments).
-  - Never fabricate synthetic BLOCK findings to look thorough; if the spec holds, issue an immediate GO verdict.
-  - Review hardens the spec; it does NOT alter user intent or product direction.
-
----
-
-## Phase 4: Output Execution & Verification
-
-Emit the review verdict and go/no-go gate:
-
-```markdown
-## Review Verdict
-
-### BLOCK (must resolve before build)
-- [B1] Finding — evidence (file:line or doc citation) — remedy.
-
-### HARDEN (drafted §V invariants)
-- [H1] Draft V<N>: <testable invariant guarding behavior>
-
-### NOTE
-- [N1] Finding [unverified] — suggestion.
-
-### Gate
-- **Verdict**: [GO | NO-GO]
-- **Next Step**: [If NO-GO: resolve BLOCKs via spec; If GO: proceed to /build]
-```
+Scale review to the actual change. Do not introduce a separate approval or invocation
+requirement for routine work. Follow [shared workflow](../../protocols/workflow.md).