scan-invariants

name	scan-invariants
description	Check whether a codebase upholds its invariants — a specific theme or all themes in parallel. Use when asked to review conventions, check invariants, or audit codebase health.
argument-hint	[architecture | design | code-quality | type-design | correctness | assertions | error-handling | security | privacy | data-integrity | testing | observability | performance | concurrency | reliability | documentation | api-design | cli-design | dependencies | deployment | config | python | rust] [optional: path/glob or git-range e.g. src/api/ or main..HEAD]
model	opus
effort	high

Dispatch

If the user specified a theme:

1. Read ~/.claude/references/README.md to understand the invariant framing and tier definitions
2. Load ~/.claude/references/<theme>.md (list ~/.claude/references/ if unsure which file applies)
3. Study the current project's documented guidance for this concern (if any)
4. Use up to 50 subagents to explore the codebase (or the path/git-range if the user specified a smaller scope)
5. Identify violations of Must invariants, deviations from Should invariants, and unresolved Consider tradeoffs
6. Focus especially on patterns you would not want a future agent to spread

If no theme was specified, continue below for a full parallel review.

---

Important: stay in your coordinator role

Do NOT invoke any Skill tools yourself. Instead, launch 7 Agent subagents in a single message (so they run in parallel), with each review's full prompt inlined as shown below.

Full review

1. Read ~/.claude/references/README.md and all reference files for each cluster below. Then launch all 7 Agent subagents in a single message, scoped to the entire codebase (or subsection if the user specified a smaller scope). Paste the relevant reference file contents into each agent's prompt. Each agent should return a structured list of findings with severity, location, and recommendation.

   Each subagent's prompt must include:

   • The full content of the relevant reference files
   • The tier definitions from README.md
   • This shared task: "Use up to 50 subagents to explore the codebase. Identify violations of Must invariants, deviations from Should invariants, and unresolved Consider tradeoffs. Focus especially on patterns you would not want a future agent to spread. Return findings as a structured list with severity (Must/Should/Consider), location, and recommendation."

   Subagent 1 — Structure (subagent_type: Explore, description: "review structure") Inline: ~/.claude/references/architecture.md, ~/.claude/references/design.md, ~/.claude/references/code-quality.md

   Subagent 2 — Types & Correctness (subagent_type: Explore, description: "review types and correctness") Inline: ~/.claude/references/type-design.md, ~/.claude/references/correctness.md, ~/.claude/references/assertions.md, ~/.claude/references/error-handling.md

   Subagent 3 — Security & Privacy (subagent_type: Explore, description: "review security and privacy") Inline: ~/.claude/references/security.md, ~/.claude/references/privacy.md

   Subagent 4 — Data (subagent_type: Explore, description: "review data integrity") Inline: ~/.claude/references/data-integrity.md

   Subagent 5 — Testing (subagent_type: Explore, description: "review testing") Inline: ~/.claude/references/testing.md

   Subagent 6 — Operations (subagent_type: Explore, description: "review observability, performance, concurrency, and reliability") Inline: ~/.claude/references/observability.md, ~/.claude/references/performance.md, ~/.claude/references/concurrency.md, ~/.claude/references/reliability.md

   Subagent 7 — Documentation & Release (subagent_type: Explore, description: "review documentation, API design, dependencies, deployment, and config") Inline: ~/.claude/references/documentation.md, ~/.claude/references/api-design.md, ~/.claude/references/dependencies.md, ~/.claude/references/deployment.md, ~/.claude/references/config.md

   Note: include language-specific files in the relevant agents when applicable: ~/.claude/references/python.md → Types & Correctness (if Python); ~/.claude/references/rust.md → Types & Correctness (if Rust); ~/.claude/references/cli-design.md → Structure (if the project has a CLI binary).

2. Wait for all subagents to return their results

3. Explore specific areas of the codebase yourself if needed to compare the relative importance of findings

4. Rank findings by priority (impact, cost of delay, ROI)

5. Present the prioritized findings with a summary table

6. Generate a self-contained HTML slide deck:

   • mkdir -p .outputs/<yyyy-mm-dd>
   • Write to .outputs/<yyyy-mm-dd>/scan-invariants.html — clean minimal styling, one slide per category plus a title/summary slide, keyboard arrow-key and click navigation
   • open .outputs/<yyyy-mm-dd>/scan-invariants.html

7. Recommend a next action and wait for the user's response