--- name: architecture-review-full version: 2.1.0 description: '[Architecture] Use when auditing the ENTIRE project architecture and production readiness in one pass — bundles architecture-review + architecture-scalability-review + production-readiness-review at project or diff scope, then synthesizes one consolidated Architecture Health Report.' --- > **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. > **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends. > **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason. > **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions. ## Quick Summary **Goal:** Audit the WHOLE project's architecture, scalability posture, and production readiness in ONE pass by orchestrating the three deliberately-non-overlapping sibling reviewers, then de-duplicating their intentional cross-references into ONE consolidated Architecture Health Report — this skill is a THIN orchestrator, it does NOT re-implement any of the three reviews. **Summary:** - **Purpose:** resolve scope once, fan three reviewers out as parallel read-only sub-agents behind an all-return barrier, PROGRESSIVELY synthesize + dedup each child's findings into ONE report file (status `IN PROGRESS` → `FINISHED`), run a `/why-review` fix gate that walks each review face, then finalize the combined verdict. Read-only until findings are validated — fixes route to a downstream `/plan` or feature flow. - **The three children — deliberately non-overlapping siblings that cross-reference each other, so their findings MUST be deduped:** - `architecture-scalability-review` (subagent `architect`) — project-grading scorecard `/20` + pass/fail gates. ALWAYS grades the project, even under diff scope (project-grader by design, "not the every-change diff reviewer"). - `architecture-review` (subagent `architect`) — diff/scope-scoped 13-category PASS/WARN/BLOCKED compliance. Its Category 11 delegates full scalability/coupling grading to `architecture-scalability-review`. - `production-readiness-review` (subagent `code-reviewer`) — service/API SRE `/24` + 8-item Extended SRE Readiness gate. `architecture-scalability-review` routes runtime readiness here. - **This skill runs INLINE** in the main session because it spawns sub-agents; the three children are each 25k–34k tokens and CANNOT run inline together — they MUST be sub-agents. - **Dedup is the core value.** Because the three siblings intentionally cross-reference each other, the same underlying issue surfaces from multiple angles; record it ONCE citing every source, preserve each child's route-to-sibling pointers. — why: undeduped, three intentionally-cross-referencing reviewers inflate severity counts and bury distinct issues. - **Coverage sweep + self-audit are orchestrator-only duties (Step 4).** After `Faces merged: 3/3`, sweep the merged report against the design-review script (`architecture-knowledge.md` §20.2) and record every unanswered question as an INFO `Coverage gap` line; frame remaining risk against the five judgments (§20.4); then run the 11 thinking red flags (§20.3) across the merged findings before Step 5. — why: three correctly-in-lane reviewers cannot see a question that belongs to no lane, and synthesis is where their confirmation biases compound. **Workflow:** 1. **Step 1: Resolve Scope** — `$ARGUMENTS` or `AskUserQuestion`; map the chosen scope to each child's args. 2. **Step 2: Load Project Reference Docs Once** — warm shared context before fan-out. 3. **Step 3: Parallel Fan-Out (all-return barrier)** — spawn all three read-only sub-agents in ONE message; advance only after ALL three return. 4. **Step 4: Progressive Synthesis (IN PROGRESS)** — open the ONE consolidated report at status `🚧 IN PROGRESS` when fan-out starts; merge + dedup each child's findings into it AS that child returns — never held in memory to the end; then run the §20.2 coverage sweep and the §20.3 self-audit over the merged set. 5. **Step 5: Fix-Report-Per-Review `/why-review` Gate** — ONE merged `/why-review` pass that walks each of the three review faces + the dedup and fixes the report in place (severities, false positives, dedup-dropped issues). 6. **Step 6: Finalize (FINISHED)** — lock the combined verdict (worst-case rollup) and flip the report status to `✅ FINISHED`. 7. **Next Steps** — `AskUserQuestion`: `/plan` (fix validated findings) / `/code-simplifier` / skip. **Key Rules (top 3 critical first):** - MUST ATTENTION this is a THIN orchestrator — NEVER re-implement any of the three reviews inline; fan them out as sub-agents and synthesize. - MUST ATTENTION dedup the intentional overlaps — one underlying issue = one finding citing every reporting child; NEVER let cross-referencing siblings triple-count it. - MUST ATTENTION read-only until validated — run the Step 5 `/why-review` gate before handoff; fixes route to a downstream `/plan`/feature flow, NEVER applied here. - Spawn all three sub-agents in ONE message and honor the all-return barrier — advance only after every child returns (`SYNC:parallel-phase-advancement` discipline). - Write the consolidated report to `plans/reports/architecture-full-review-{YYMMDD}-{HHmm}-{slug}.md`. ## Your Mission $ARGUMENTS ## Review Mindset (NON-NEGOTIABLE) Skeptical synthesizer. Judge the three children's reports; do not re-derive them. - Trust each child's `file:line` evidence, but NEVER inflate severity by counting the same underlying issue three times — dedup first, then rank. - A finding survives to the report only after the Step 5 `/why-review` gate; an unvalidated sub-agent claim is a hypothesis, not a finding. - Preserve every route-to-sibling pointer a child emits — the combined report is the union of owned findings, not a re-review. ## Step 1: Resolve Scope (ASK EACH RUN) Decide audit scope, then map to each child's arguments. - If `$ARGUMENTS` names files/dirs, or contains `full` / `whole` / `diff` / `changes`, use that directly. - Else `AskUserQuestion`: - **"Whole project (Recommended)"** — audit the entire repository. - **"Current changes (diff)"** — audit the uncommitted diff only. - **"Specific path"** — audit a named service/module/directory. **Scope → child args mapping:** | Chosen scope | `architecture-scalability-review` | `architecture-review` | `production-readiness-review` | | ---------------------- | ------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------- | | Whole project | `mode=audit` over the whole repo | scope override `full codebase` | args = all backend service/API roots (per `project-structure-reference.md`) | | Current changes (diff) | `mode=audit` focused on the services/modules the diff touches | default uncommitted diff | default uncommitted service/API diff | | Specific path | `mode=audit` scoped to that path's services/modules | scope override = that path | that path's service/API files | > **MUST ATTENTION — `architecture-scalability-review` always grades the PROJECT, even under diff scope.** A project-grader by design ("do not use as the every-change diff reviewer"). Under diff scope it still emits the `/20` scorecard, focused on the services/modules the diff touches — it never degrades into a pure per-line diff reviewer. Document this nuance in the consolidated report so its scorecard is read as a project posture, not a diff verdict. ## Step 2: Load Project Reference Docs Once Warm shared context BEFORE fan-out so synthesis reasons from the same ground truth the children use. Read once here (each child re-reads what it needs via its own tool calls): - `docs/project-config.json` - `docs/project-reference/project-structure-reference.md` - `docs/project-reference/backend-patterns-reference.md` - `docs/project-reference/frontend-patterns-reference.md` - `docs/project-reference/code-review-rules.md` - Accepted ADRs under `docs/adr/**`, when present ## Step 3: Parallel Fan-Out (ALL-RETURN BARRIER) Spawn ALL THREE sub-agents in ONE message. Read-only and independent — no shared mutable state, no ordering dependency. Advance ONLY after EVERY member returns (`SYNC:parallel-phase-advancement`). Each sub-agent writes its FULL report to `plans/reports/` and returns ONLY the `SYNC:subagent-return-contract` summary (≤10 finding bullets + report path) — NEVER its full report inline. | # | Child skill | `subagent_type` | Whole-project args | Diff-scope args | Emits | | --- | --------------------------------- | --------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------- | | 1 | `architecture-scalability-review` | `architect` | `mode=audit` over whole repo | `mode=audit` focused on the diff's services/modules (still grades the project) | Scorecard `/20` + pass/fail gates | | 2 | `architecture-review` | `architect` | scope override `full codebase` | default uncommitted diff | 13-category PASS/WARN/BLOCKED | | 3 | `production-readiness-review` | `code-reviewer` | all backend service/API roots (per `project-structure-reference.md`) | default uncommitted service/API diff | SRE `/24` + 8-item gate | Each sub-agent prompt states: READ-ONLY findings/score mode (no fixes); re-read all target files from scratch via its own tool calls; write full report incrementally to `plans/reports/`; return only the return-contract summary. **Each of the three faces feeds TWO validation gates downstream — state this in each sub-agent's prompt so it knows its findings will be adversarially validated, not trusted as-is:** (1) the Step 5 fix-report-per-review `/why-review` gate that walks its face and fixes its findings in the consolidated report; (2) inside `workflow-architecture-audit`, the workflow-level FINAL `/why-review` gate that re-reviews the whole finalized report. A face's findings are hypotheses until they survive both — so every finding it emits MUST carry `file:line` proof + confidence that can withstand validation. ## Step 4: Progressive Synthesis → One Report (status `IN PROGRESS`) Exactly ONE report file for the whole audit — created ONCE, grown across Steps 4→6, never re-created per review. Open it when fan-out starts and evolve its status through its lifecycle: `🚧 IN PROGRESS` (Step 4) → `🔍 VALIDATING` (Step 5) → `✅ FINISHED` (Step 6). Write to `plans/reports/architecture-full-review-{YYMMDD}-{HHmm}-{slug}.md`. **On fan-out start — create the file with status `🚧 IN PROGRESS`** and a status line naming which of the three review faces have returned so far (e.g. `Faces merged: 0/3`). The single source of truth the whole audit synthesizes into — do NOT hold findings in memory until the end. **Header — all three sub-scores + ONE combined verdict** (each sub-score is `⏳ pending` until its face returns): - Scalability Scorecard: `X/20` + verdict (STRONG / NEEDS WORK / HIGH RISK) - Architecture Compliance: PASS / WARN / BLOCKED - SRE Readiness: `X/24` + verdict (PASS / NEEDS WORK / NOT READY) - **Combined Verdict:** `⏳ pending until FINISHED` — computed in Step 6 as the worst-case rollup across the three (any BLOCKED / NOT READY / HIGH RISK dominates). Do NOT assert a combined verdict while status is `IN PROGRESS`. **Merge each face AS it returns.** All three run behind the Step 3 all-return barrier, so all three summaries are in hand before synthesis — but merge them into the file one face at a time (updating `Faces merged: N/3` each time) so a mid-synthesis context loss leaves the partial report on disk, not in memory. When ≥2 children report the same underlying issue, record it ONCE, citing every source. Dedup on these KNOWN overlap axes (the siblings cross-reference each other here by design): | Overlap axis | `architecture-review` face | Sibling face(s) | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Module isolation / loose coupling / horizontal scaling / DRY regression | Category 11 (scalability & coupling regression) | `architecture-scalability-review` {module isolation, loose coupling, horizontal scaling, DRY} | | Quality tooling / CI / observability | Category 0 (quality-tooling baseline) | `architecture-scalability-review` {Build & CI, Observability} | | Recorded-decision / clean-architecture conformance | Category 9 (ADR conformance) | `architecture-scalability-review` {clean architecture} | | DB performance / capacity ceilings | `production-readiness-review` DB-perf + capacity gate | `architecture-scalability-review` {horizontal scaling} | | Technique applicability (advisory) — scale-tier technique matrix | Category 11 INFO advisory matrix | `architecture-scalability-review` + `production-readiness-review` advisory matrices | | Scenario stress (advisory) — big-traffic/big-data/failure/self-heal | Category 11 INFO scenario-stress matrix | `architecture-scalability-review` + `production-readiness-review` scenario-stress matrices | | Data / consistency / tenancy — dual write, idempotency, breaking migration, tenant isolation | Category 12 (data, consistency & tenancy boundaries) | `production-readiness-review` {migration safety, rollback}; `security-review` owns authz depth; `performance-review` owns query-plan depth | For each merged finding: assign ONE severity per `SYNC:severity-rubric` (do not sum severities across duplicate reports), cite each reporting child's `file:line`, and PRESERVE each child's route-to-sibling pointers. — why: undeduped, three intentionally-cross-referencing reviewers inflate severity counts and bury distinct issues. **Merged advisory Technique Applicability Matrix (does NOT change the combined verdict):** all three children emit a scale-tier Technique Applicability Matrix from `SYNC:scale-technique-gate`; dedup the three views of the same technique onto ONE advisory matrix in the consolidated report. **Pin ONE authoritative scale tier for the merged matrix — `architecture-scalability-review`'s derived tier is canonical (owns scalability grading); if another child's derived tier DIVERGES, record the divergence as a one-line note and key the merged matrix's `tier-warranted?` column to the pinned tier, rather than merging contradictory warranted-sets.** This only SELECTS which already-derived tier the matrix is keyed to — it does NOT re-derive any child's findings (respecting "you do not re-derive them" above). It is **advisory/INFO only** — a `MISSING-WARRANTED` technique is guidance, never a severity, and NEVER feeds the worst-case combined-verdict rollup. This orchestrator adds no own gate marker; the matrix is inherited from the children. **Merged advisory Scenario Stress Matrix (does NOT change the combined verdict):** the same three children each emit a Scenario Stress Matrix from `SYNC:scenario-stress-eval` (top-down: big-traffic / big-data / dependency-failure / node-loss / data-corruption / self-heal survival vs. business need). Dedup the three views of the same scenario onto ONE advisory matrix in the consolidated report, exactly as for the technique matrix. **Pin ONE authoritative scale tier AND business-criticality read — `architecture-scalability-review`'s derived `T`-tier + `B`-tier is canonical (owns scalability grading); if another child's derived tier/criticality DIVERGES, record it as a one-line note and key the merged matrix to the pinned values, rather than merging contradictory in-scope sets.** This only SELECTS which already-derived tier/criticality the matrix is keyed to — it does NOT re-derive any child's scenario findings. It is **advisory/INFO only** — a `FAILS-HARD` or `OVER-HARDENED` scenario is guidance, never a severity, and NEVER feeds the worst-case combined-verdict rollup. The criticality-signal floor and anti-over-engineering guard live in the children's matrices; this orchestrator adds no own gate marker and inherits the matrix from the children. **Completeness lens over the merged set (orchestrator-only — the children cannot see across faces).** Once `Faces merged: 3/3`, sweep the merged report against the design-review script in `.claude/docs/architecture-knowledge.md` §20.2 and record any question NO face answered as an explicit `Coverage gap: {question} — not covered by any face` line. Frame each remaining risk against the five judgments in §20.4 — _when to add complexity · when to split · when consistency can be relaxed · when to buy vs build · when GOOD ENOUGH is correct_ — so the consolidated report tells the reader which JUDGMENT is at stake, not only which rule was broken. A coverage gap is an INFO note, never a severity, and NEVER feeds the combined-verdict rollup. — why: three scoped reviewers each correctly stay in lane, so a question that belongs to no lane is invisible to every one of them and only this orchestrator can see it. **Self-audit the merged report (MANDATORY before Step 5):** run the 11 thinking red flags in §20.3 across the merged findings — especially **a recommendation whose SACRIFICE is unnamed**, **"best practice" with no named forces**, and **a scale claim with no evidence**. Any hit is demoted or removed here, not passed to `/why-review` as ground truth. — why: the orchestrator's synthesis is where three children's confirmation biases compound into one authoritative-sounding report. Step 4 ends only when `Faces merged: 3/3` — all three sub-scores are populated, the §20.2 coverage sweep is recorded, and every finding is on disk. ## Step 5: Fix-Report-Per-Review `/why-review` Gate (status `VALIDATING`) — MANDATORY when findings exist Flip the report status to `🔍 VALIDATING`, then run ONE merged `/why-review` pass that WALKS EACH of the three review faces (one merged pass, NOT three per-face passes — a single invocation is strictly more thorough because it also