--- name: foundational-review description: "Run a verdict-led foundational review before an irreversible decision such as a version freeze, schema/spec tag, public API/repo flip, major re-scope, or keep/kill moment. Produces findings sections A-F, premises, irreversibility inventory, specs, cold-executable plans, prospect amendments, and a kickoff. Requires a named decision; otherwise redirect to /prospect or /readiness-audit." argument-hint: " [--decision \"\"] [--extend]" allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch, Skill, Task --- # /foundational-review — "Is this the right thing, built the right way?" Run a repeatable, model-agnostic review of a project at the FOUNDATIONS — problem–solution fit, architecture soundness, product coherence — and convert the findings into a prospect-hardened, cold-executable plan with owner routing. This is the productized form of the foundational review chain (the canonical process doc this skill reads at Step 1). This skill is **orchestration + artifact templates only**. The substance — the A–F review questions, the operating rules, the failure-mode library, the pairing contract — lives in the canonical process doc, which Step 1 reads in full. Do not reproduce that doc's content from memory; read it live every run so the chain evolves in one place. **What this is NOT** (the process doc opens with this — internalize it): - **Not a code review** — code review asks "are these changes correct?" on a diff. This asks "should this shape exist?" on a decision. - **Not a readiness audit** — `/readiness-audit` checks a surface against a checklist and produces a findings list. This produces a VERDICT resting on named PREMISES plus the full execution handoff. Siblings, not substitutes (see the pairing contract in the Step 1 doc and Step 0's pairing check). - **Not a retrospective** — `/retrospect` validates shipped work backward. This judges a standing architecture/product forward, before an expensive-to-undo step. ## When to use Run it before any IRREVERSIBLE decision — the anchor: - A version freeze or stable-contract claim - A format / schema / spec tag (e.g., a `v1.0` spec freeze) - A public API surface or a repo public-flip - A major re-scope, pivot, or "should we keep building this at all" moment **No irreversible decision named → do not run this chain.** Redirect: - A plan that's about to execute → `/prospect` - A surface to check clean/legal/consistent for shipping → `/readiness-audit` - Already-shipped work to validate backward → `/retrospect` ## Step 0: Invocation Block Parse `` (first positional), `--decision ""`, and `--extend`. Then assemble the invocation block. If args are thin, collect interactively — **one ask at a time**: ``` Invocation: Scope root: Read-first: THE irreversible decision: Section-F inputs: Constraints: Reviewer model: Extend?: ``` **Hard gate — the decision anchor.** If no irreversible decision can be named (the `--decision` arg is absent AND the user can't state one when asked), STOP and redirect: > This chain is decision-anchored — it needs one expensive-to-undo step to anchor the verdict and the irreversibility inventory. You haven't named one. Did you mean: > 1) `/prospect ` — pre-mortem a plan that's about to execute > 2) `/readiness-audit --for ""` — audit a surface for ship-readiness > 3) I'll name the irreversible decision now: Do not invent a decision to keep the chain running. **Pairing check.** If THE irreversible decision is a SHIP / FREEZE / PUBLIC-FLIP, the canonical pairing rule says run BOTH the audit (for the surface) and the chain (for the decision). Ask: > This decision is a ship/freeze/flip. The pairing contract recommends running `/readiness-audit` first (cheaper, produces the evidence base the review can lean on). Run `/readiness-audit --for ""` now, then resume this chain? (`y` / `n` / `already-have-one`) On `y`, invoke `/readiness-audit` via the `Skill` tool, then resume at Step 1 with the audit as admissible evidence (per the composition contract — the review re-derives every inherited claim, never trusts the audit's attributions/counts without a fresh sweep). ### Model Routing - **Reviewer = the highest-ceiling model available** (escalate to the top tier only when the decision is extreme-stakes; the default top model otherwise). The ceiling is spent on alternatives steelmanning (§A), portfolio/product judgment (§F), and the irreversibility inventory. **The default model can run the full chain** — it compensates with stricter evidence-sourcing in the /prospect passes. - **Executor = the default model by default.** Every plan task (Step 4) carries `OWNER: ` unless its *execution* needs extreme judgment — justify any top-tier owner in one line, or it's rewritten to the default. - **Gate owner = the human.** Anything needing sign-off becomes a named gate `G-A..` in the spec (Step 3), never an inline assumption. - **Effort ladder (when the reviewer is the top-tier model):** default `xhigh` for every substantive review — these passes are semi-agentic (read files, trace seams) and `xhigh` is built for that read-trace-reason loop; it also matches *why* you escalated to the ceiling. Use `high` only for light surfaces (small/on-hold/PRD-only projects). Reserve `max` for the single hardest correctness-dominated pass (e.g. auth-across-tenancy, ledger/tax invariants) — elsewhere it over-deliberates without adding signal. Running the top model at plain `high` is the worst-value point: if `high` feels like enough, the default model at `high` would have sufficed. ## Step 1: Load the Canonical Process & Survey 1. **Load the canonical chain.** Read the canonical process doc, preferring a user copy when present: - If `/approaches/foundational-review-chain.md` exists (resolve `` from `~/.claude/aria-knowledge.local.md`), read THAT — a user may keep a richer, project-specific copy there. - Otherwise read the plugin-bundled copy at `${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/foundational-review/foundational-review-chain.md` (always present). It carries the operating rules, the A–F questions, the artifact conventions, the failure-mode library, and the pairing/extension specs. Hold it in context — every later step references it by section rather than restating it. 2. **Load the failure-mode libraries** (mirrors /prospect Step 2): `/rules/retrospect-patterns.md`, and `/rules/prospect-patterns.md` + `/projects//{retrospect,prospect}-patterns.md` if they exist for the detected project. 3. **Survey the tree.** Read the read-first docs, then walk the actual source tree. **READ BEFORE JUDGING** (operating rule 1): every load-bearing claim is cited as `file:line`, verified THIS session — never asserted from memory, docs, or prior-session summaries. 4. **Bound the scope** (operating rule 2): state in-scope and out-of-scope explicitly; fence sibling workstreams by reference. For a multi-repo family, **group by coupling mechanism**: shared-runtime repos → review as ONE super-project (hub-out from the shared dependency, ~20% grounding / ~80% on the seams); protocol- or file-contract repos → review each side standalone + review the *contract* once from the producer side; a vendored copy → not a review seam at all. The same portfolio can contain all three. 5. **Run empirical probes** read-only (`git log`, `grep`, file-existence). **VERIFY FORMATS, NOT JUST LOCATIONS** (operating rule 6): any later plan step that parses/renames/sweeps is preceded by an enumeration sweep at planning time. ## Step 2: Findings Document Write `/FABLE-REVIEW-.md` (keep the reviewer-named filename for provenance even when the default model runs it; state the actual model in the header). Structure: ``` # Foundational Review — — Reviewer model: | THE irreversible decision: ## Verdict + the single most important reason (one sentence). ## Premises | ID | Premise the verdict rests on | If it changes… | |----|------------------------------|----------------| | P1 | … | … | ## A. Problem–Solution Fit Steelman 2–3 alternative framings (include "do nothing / minimal" and "kill / fold elsewhere"); for each: wins, costs, verdict + PRESERVED rationale (why-rejected stays answerable). ## B. Foundational Correctness Name each weak premise being patched around + the fix-at-base. ## C. Built Right Data model · abstraction layers (flag any beyond ~3 that don't earn their cost) · coupling/seams · testing & validation · characteristic failure modes (especially SILENT ones). ## D. Gaps Smallest set of missing capabilities that makes it "v-next worthy." Assign existing owners; don't re-own. ## E. Over-build What exists that the use case doesn't justify. Cut = archive-with-pointer or policy-freeze, not deletion. Includes DOC decay (stale plans, falsified bug reports a cold executor would burn time on). ## F. Product / Portfolio Coherence Boundaries (free/premium, public/private) · monetization/positioning · family coherence · licensing/IP posture. ## Irreversibility Inventory | What becomes expensive after the tag | Why | Precision the handoff needs | ## Uncertainty Flags Predictions ≠ findings — say which is which. ``` **Scale to the finding:** one change → findings + a short plan; large review → findings + several specs + plans. A re-scope/reconsider verdict's spec/plan may be a wind-down or pivot plan — that's a valid output. ## Step 3: Design Spec(s) Per substantive change, write `docs/superpowers/specs/--design.md` (use the project's existing `docs/superpowers/` convention): ``` ## Decisions D1: what · why · smallest version · rejected alternatives (with preserved rationale) … ## Gates G-A: decision needed · what it blocks · default-if-unanswered (or "hard gate, no default") … ## Non-goals ## Sibling-workstream fencing " owns — not duplicated here." ``` Minor items stay as plan rows; only substantive changes get a spec. ## Step 4: Plan(s) Per spec, write `docs/superpowers/plans/-.md`. Tasks must be COLD-EXECUTABLE with no access to the reviewer's reasoning: - Exact paths, supplied code/content, commands + expected output, acceptance criteria, dependency sequence. - `OWNER:` per task (default executor; justify any top-tier owner in one line). - An **execution-notes preamble**: build rules, restore steps, no-push, named-path commits, known-baseline counts (test counts, file counts). - **Team-owned repos:** the unit of execution is a tracker ticket (Product + Technical Intake), NOT a code edit. ## Step 5: Compose /prospect Run `/prospect` on each plan (file scope) via the `Skill` tool: > Use the `Skill` tool to invoke `prospect` with `file `. Then **APPLY verdict-changing amendments IN PLACE** — don't just score the plan. Validated runs' /prospect passes falsified *format* assumptions (line-anchored tokens that were `var()` indirections; hex colors that were RGB triplets; a 4-file rename that was a 14-file surface). After amending, stamp the verdict + amendment list into the plan header. The prospect log lands in `/logs/prospect/` via the composed skill — do not duplicate that routing here. ## Step 6: Failure-Mode Self-Check, Commit & Kickoff **Pre-commit self-check (mandatory).** Run the plan(s) against the "Failure modes this process has already caught" list in the Step 1 process doc — this is the chain's equivalent of /prospect's pattern check. At minimum confirm: - `fix-without-call-site-audit` — no rename/sweep step written only from the sites the review happened to verify - Un-sourced FORMAT assumptions — every parse/rename/sweep preceded by an enumeration sweep - Misattributed file claims inherited from a sibling audit — re-derived by sweep, never inherited - "Verification" runs that mutate build artifacts — every test-build step carries an explicit RESTORE + `git diff --stat` check - Plan/idea-dump decay — no stale/falsified backlog items inside the plan - History rewriting in mechanical sweeps — live-vs-historical surfaces split before any `sed` **Commit** the artifacts (named paths, no push — pushing is the owner's separate gate per operating rule 8). If `Bash`/`git` is unavailable, emit copy-paste commit messages instead. **Kickoff.** End with a paste-ready executor kickoff: ``` ## Executor Kickoff Plan(s): Task order: <#1 → #2 → …, note dependency gates> Owner routing: Definition of done: Open gates: Report back: ``` ## Step 7 (optional): Extension Loop `--extend` Run only when the owner wants the deeper "is the SYSTEM itself good engineering?" layer. Follow the process doc's "extension loop" section: 1. **System-design assessment** appended to the findings doc (§11-style): novelty ranked by defensibility; honest weaknesses; abstraction-architecture verdict; ranked improvement ladder; assessment uncertainties (mark untested claims benchmarkable). Look for ONE unifying critique — a single lens explaining all improvements signals the analysis converged. 2. **Durable capture** — the unifying critique → a canonical pattern file (`projects//patterns/` or `approaches/`); session arc → project memory + memory index. Reuse `/extract` routing rather than duplicating it. 3. **Second chain** — improvement ladder → roadmap SPEC (waves W0 enforce-existing · W1 evidence probes each with a NAMED FALSIFICATION OUTCOME · W2 architecture evolutions gated on W1) → `/prospect` → wave-executable PLAN → `/prospect` → commit. Probes-before-architecture is the spine. ## Step 8: Outputs & Intake - **Findings:** `/FABLE-REVIEW-.md` - **Specs/plans:** the project's `docs/superpowers/{specs,plans}/` - **Prospect logs:** via the composed `/prospect` (Step 5), in `/logs/prospect/` - **Extension captures:** via `/extract` (Step 7), if `--extend` - **Aria intake:** suggest backlog entries (insights / decisions / approaches) per the standard intake confirmation flow — suggest, user reviews, write on approval. ## Step 9: Validation Gates Before declaring the chain complete, verify: 1. **Decision anchor present?** THE irreversible decision is named in the findings header. (If absent, the chain should have redirected at Step 0.) 2. **Read-before-judging honored?** Every load-bearing claim in the findings cites `file:line` verified this session. 3. **Verdict from the fixed vocabulary?** One of foundationally-sound · sound-with-changes · re-scope · reconsider, with its single most-important reason. 4. **Premises table present** with "if it changes" for each. 5. **Sections A–F all answered** (or marked N/A with reason) + irreversibility inventory + uncertainty flags. 6. **Specs carry D-decisions + gates;** plans are cold-executable with OWNER per task + execution-notes preamble. 7. **/prospect composed on every plan,** amendments applied IN PLACE, verdict stamped into the plan header. 8. **Pre-commit failure-mode self-check ran** against the process doc's list. 9. **Artifacts committed (named paths, no push);** kickoff emitted. 10. **Pairing honored** — if the decision was a ship/freeze/flip, either a `/readiness-audit` was run/referenced or the user explicitly declined. If any check fails, self-correct once; if it can't be closed (e.g., a gate is unanswered), surface the gap explicitly rather than silently skipping.