Architecture Scalability Review

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
• User-question prompts mean to ask the user directly in Codex.
• Ignore Claude-specific mode-switch instructions when they appear.
• Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
• For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
• If a required step/tool cannot run in this environment, stop and ask the user before adapting.

Codex Project-Reference Loading (No Hooks)

Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.

Always read:

• docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
• docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
• docs/project-reference/lessons.md (always-on guardrails and anti-patterns)

Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.

Situation-based docs:

• Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): project-structure-reference.md
• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec authoring, docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
• Behavior/public-contract changes or spec-test-code sync: workflow-spec-test-code-cycle-reference.md plus the spec docs above
• Derived spec indexes/ERDs/reimplementation guides: spec-system-reference.md and source Feature Specs under docs/specs/
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.

Quick Summary

Goal: Grade a project or planned architecture against the full architecture + scalability quality scorecard, routing deep checks to the existing owner skills instead of duplicating them — so the project earns an evidence-backed /20 verdict (STRONG / NEEDS WORK / HIGH RISK) before scale or delivery hardens the decisions.

Summary:

• This skill is the scorecard OWNER, not the deep owner — it scores 10 areas 0-2 (/20), then routes sibling-owned depth (architecture-design/review, domain-analysis, performance-review, production-readiness-review, security-review, linter-setup, scaffold) via the Ownership Matrix; NEVER expand into a sibling's checklist.
• Scoring is evidence-gated — file:line/command/artifact proof or explicit N/A - reason, else 0; then 7 pass/fail gates (G1-G7) overlay the score without changing the /20 math.
• Before emitting, self-audit every grade against the 11 thinking red flags (architecture-knowledge.md §20.3) — a deduction for unevidenced scale, a tool named before the requirement, or a recommendation whose sacrifice you cannot state is re-derived or dropped, NEVER reworded. A — VERIFY row or section banner in architecture-knowledge.md §3/§8/§9/§10 is UNVERIFIED — it can never be the sole basis for a deduction; confirm against the named source or the project's own docs.
• Two conditional advisory gates ride along — Technique Applicability + Scenario Stress — emitting guidance ONLY; NEVER mutate the /20 score, verdict band, or gate pass/fail.
• Runs in mode=init (planned greenfield architecture) or mode=audit (existing brownfield source/config/CI/ADR evidence).

Workflow (run in order):

1. Resolve mode=init or mode=audit + target scope.
2. Load project context and evidence.
3. Read references/scorecard.md.
4. Score all 10 areas 0-2 with evidence.
5. Run pass/fail gates (G1-G7).
6. Emit the architecture scalability review report under plans/reports/.

Key Rules:

• MUST ATTENTION every score carries file:line, command output, architecture-artifact evidence, or explicit N/A - reason; unproven criteria score 0.
• MUST ATTENTION this skill owns the scorecard, not the deep review of every concern — route depth to the sibling skills named in the Ownership Matrix; NEVER duplicate their checklists.
• New Tech/Lib: N/A by default. If the audit recommends Nx, Turborepo, Bazel, a new message broker, a new observability stack, or any other tool, present it for user confirmation before implementation.
• mode=init scores planned architecture from greenfield artifacts before implementation planning; mode=audit scores an existing brownfield project from real source, config, CI, docs, and ADR evidence.

When To Use

• Greenfield/project-init flow after architecture-design, before implementation planning hardens decisions.
• On demand against an existing repository when the user asks to review project quality, architecture scalability, distributed-monolith risk, module boundaries, build scalability, or setup quality.
• Periodic architecture health check for a growing codebase.

NEVER use this as the every-change diff reviewer. Per-change regression checks belong in architecture-review, performance-review, production-readiness-review, and other sibling reviewers already wired into workflow-review-changes.

Combined audit: For a whole-project architecture + compliance + production-readiness audit in one pass, run $architecture-review-full (or $start-workflow workflow-architecture-audit) — it fans out this skill, architecture-review, and production-readiness-review as parallel sub-agents and synthesizes one consolidated report.

Scope And Modes

mode=init

Score intended architecture before implementation exists. Evidence may include architecture reports, ADRs, tech-stack decisions, domain-analysis outputs, build/CI plans, deployment plans, and scaffold handoff tables.

Use planned evidence labels when implementation is not yet present. Score 2 only when the plan names enforceable mechanisms, not intent alone.

mode=audit

Score an existing repository. Evidence must come from source files, build config, CI config, ADRs, reference docs, tests, dependency-boundary tooling, deployment/IaC files, and graph/grep commands.

If .code-graph/graph.db exists, run at least one graph command on key architecture files before concluding.

Required Context

Read these before scoring:

• docs/project-config.json
• docs/project-reference/docs-index-reference.md
• docs/project-reference/lessons.md
• docs/project-reference/project-structure-reference.md
• Relevant stack docs from the docs index, based on target scope
• Accepted ADRs under docs/adr/**, when present
• Existing architecture, domain, CI, deployment, and observability artifacts in the target plan or repo

Ownership Matrix

When a concern belongs to a sibling, record a one-line route pointer and continue scoring from evidence. NEVER expand into the sibling's full checklist.

Workflow

Step 1: Resolve Mode And Scope

Determine:

• Mode: mode=init or mode=audit
• Target: current repo, plan directory, specific service/module, or architecture artifact set
• Evidence roots: source paths, CI/build files, ADRs, reference docs, workflow outputs
• Report slug: project/module name

If mode is missing, infer from context:

• Greenfield/project-init/plan artifacts only -> mode=init
• Existing repo/source/config review -> mode=audit

Step 2: Gather Evidence

Use narrow grep/glob searches first. For brownfield audits, collect at least:

• Build files and CI pipeline config
• Workspace/monorepo config, if present
• Dependency-boundary or architecture-rule tooling
• Module/service folder structure
• Message bus, event, API, and cross-context communication patterns
• Deployment, IaC, observability, and runtime config
• ADRs and architecture reports

Run graph trace on key architecture or module-boundary files when .code-graph/graph.db exists. If the graph lacks relevant files, record that limitation and continue with grep/file evidence.

Step 3: Score The 10 Areas

Read references/scorecard.md and score each area:

• 0 = absent, contradicted, or unproven
• 1 = partially addressed, documented but weakly enforced, or implemented in only some areas
• 2 = designed and enforced with evidence

Total score: /20.

Technique Applicability (advisory — NON-SCORING)

After scoring, invoke SYNC:scale-technique-gate: derive the system's scale tier from evidence (users/RPS, SLO, data volume, tenancy, topology — cite file:line/config/infra + confidence), then emit the Technique Applicability Matrix (technique | tier-warranted? | present? | verdict | advice | evidence) across the 10 concern groups. Surface warranted-but-missing techniques as advice AND flag OVER-ENGINEERED techniques the tier does not warrant (anti-over-engineering).

Advisory only — does NOT change the /20 score or any verdict band. A MISSING-WARRANTED technique is guidance, never a deduction; a correctly-lean small system stays a PASS. Full catalog → .claude/docs/scale-technique-catalog.md.

Step 4: Run Pass/Fail Gates

Run these gates after scoring. Gates are pass/fail overlays and do not change the /20 math.

Critical/high gate failures require an owner-accepted risk or follow-up plan before reporting STRONG.

Step 5: Emit Report

Write:

plans/reports/architecture-scalability-review-{YYMMDD}-{HHmm}-{slug}.md

Report structure:

# Architecture Scalability Review

**Mode:** init | audit
**Scope:** {project/module/artifacts}
**Date:** {date}
**Score:** {X}/20
**Verdict:** STRONG | NEEDS WORK | HIGH RISK

## Scorecard

| #   | Area | Score | Evidence | Route / Owner |
| --- | ---- | ----: | -------- | ------------- |

## Pass/Fail Gates

| Gate | Status | Evidence | Required follow-up |
| ---- | ------ | -------- | ------------------ |

## Cadence Matrix

| Area | Init/on-demand home | Every-change home | Rationale |
| ---- | ------------------- | ----------------- | --------- |

## Findings

### Critical / High

### Medium / Low

## New Tech/Lib Recommendations

List only user-confirmed recommendations or mark `N/A`.

Scorecard Validation Gate (why-review, MANDATORY when the scorecard has any sub-80 grade or risk finding)

Purpose: A scorecard is a JUDGMENT. Validate it adversarially before emitting it so a mis-scored area or an inflated risk finding does not ship as ground truth. This gate validates findings only — it routes any fix to the owning sibling review, it does NOT self-converge a fix-loop.

Trigger: Any area graded below 80, or any risk/gap finding. Skip ONLY when every area scored ≥80 with zero risk findings.

Protocol:

1. Read the finalized scorecard report from plans/reports/{skill}-{date}-{slug}.md (or the exact report path written).
2. Invoke $why-review --validate-findings <report-path> — verify each sub-80 grade and each risk finding has file:line evidence and clears why-review's finding-survival bar.
3. If why-review demotes/removes any grade or finding: update the scorecard with the revised grade/severity and add a ## Why-Review Validation Notes section citing what changed and why.
4. If the scorecard changed after validation: re-run this gate — maximum 2 validation passes — until the remaining grades/findings are validated. No fix-loop: this skill grades and routes fixes to siblings; it never restarts a full review over its own fixes.

Anti-bias (MANDATORY before emitting): steel-man each grade — argue the score should be one band better AND one band worse; a grade that survives its own steel-man ships. A scorecard whose grades were never challenged is not validated.

Self-audit against the thinking red flags (MANDATORY before emitting): run the 11 red flags in .claude/docs/architecture-knowledge.md §20.3 against every grade, gap and recommendation. The four that fire most often in a scorecard: grading down for a scale you cannot evidence · recommending a tool before stating the requirement · "best practice" with no named forces · cannot say what your recommendation SACRIFICES. Any hit invalidates the GRADE's reasoning — re-derive it from evidence or drop the finding; NEVER just reword it. — why: an unevidenced deduction reads as rigour and sends the team to fix a problem they do not have.

Completion Criteria

• All 10 areas are scored.
• Every score has evidence or explicit N/A - reason.
• All gates have pass, partial, fail, or N/A - reason.
• Cadence matrix maps each area to init/on-demand and every-change homes.
• Sibling deep checks are routed, not duplicated.

Scalability & Production-Readiness Technique Gate — CONDITIONAL, evidence-gated, scale-tiered. Judge which system-design techniques a system warrants at its scale — flag warranted-but-missing gaps AND advise AGAINST unwarranted heavyweight ones. ADVICE-ONLY: emit the matrix as guidance; NEVER mutate any score, verdict band, or gate pass/fail.

1. Derive the scale tier FIRST — from evidence, never assumed. Read users/RPS, SLO/latency targets, data volume, tenancy, topology from config/infra/specs; cite file:line + confidence. Tiers: T0 internal/single-instance · T1 small SaaS (<10k users) · T2 high-scale (10k–1M) · T3 massive/multi-region (millions+). Unknown tier → state assumption, do NOT default to T3.
2. Judge each concern group only at/above its warranting tier (member techniques → owning review skill for depth):
   • Traffic & Edge — Rate Limiting, Load Balancing, Reverse Proxy, API Gateway, CDN, Edge Caching, WAF, DDoS (T1+; CDN/WAF T2+) → security-review owns WAF/DDoS
   • Caching & Data Access — Caching, Cache Invalidation, DB Indexing, Query Optimization, N+1, Connection Pooling (T1+) → performance-review owns depth
   • Data Scaling & Consistency — Read Replicas, Sharding, Partitioning, Replication, CAP, Eventual Consistency, Locks, Leader Election (T2+; sharding/multi-region T3) → performance-review
   • Async & Messaging — Message Queues, Pub/Sub, Event-Driven, Saga, DLQ, Distributed Transactions, Backpressure, Webhooks, WebSockets/SSE (T2+)
   • Resilience — Circuit Breakers, Timeouts, Retries, Backoff, Idempotency, Health Checks, Liveness/Readiness, Failover, Graceful Degradation (T1+) → production-readiness-review
   • Scaling & Compute — Autoscaling, Horizontal/Vertical Scaling, Serverless Limits, Cold Starts, Cron Jobs, Thread Safety, GC/Memory Leaks (T1+; autoscaling T2+)
   • Deployment & Release — CI/CD, Docker, Kubernetes, Blue-Green/Canary/Rolling, Rollbacks, Feature Flags, IaC/Terraform/Helm, Build Caching (CI/CD T0+; K8s/canary T2+)
   • Observability — Monitoring, Logging, Distributed Tracing, Metrics, Alerting, SLOs/SLIs, Error Budgets (T1+; tracing/error-budgets T2+) → production-readiness-review
   • Security & Compliance — Secrets Management, IAM, OAuth, JWT Rotation, TLS, Encryption at Rest/Transit, CORS, CSRF, SQLi, XSS, SSRF (T0+) → security-review owns
   • DR & Infra — Backups, Disaster Recovery, Multi-Region, Chaos Engineering, Schema Versioning, DB Migrations, Cost Optimization (backups T1+; DR/multi-region/chaos T3) → production-readiness-review
3. Assign one of 4 verdicts per warranted technique: PRESENT · MISSING-WARRANTED (→ advise only — guidance, NOT a score/gate lever) · N/A-by-scale (below warranting tier) · OVER-ENGINEERED (present but unwarranted at this tier → advise AGAINST).
4. Anti-over-engineering guard (first-class): do NOT recommend K8s, sharding, multi-region, service mesh, event sourcing, or distributed transactions below their warranting tier. A correctly-lean small system is a PASS, never a gap.
5. Output — Technique Applicability Matrix: technique | tier-warranted? | present? | verdict | advice | evidence (file:line/config/infra). Full grouped catalog + per-tier baseline → .claude/docs/scale-technique-catalog.md. Hosting reviews surface this matrix WITHOUT changing any /20, /24, verdict band, or PASS/FAIL (per user decision 2026-07-06). Drift-guard: tier thresholds & per-technique warranting tiers are AUTHORITATIVE in .claude/docs/scale-technique-catalog.md — the inline tier summary above is a condensed pointer; on any tier/technique change, update the catalog FIRST, then re-run .claude/scripts/inject_scale_technique_gate.py to re-propagate this block.

BLOCKED until: - [ ] tier derived from evidence (not assumed) - [ ] matrix emitted - [ ] over-engineering guard applied - [ ] advisory-only (no score/verdict mutation) confirmed

Scenario Stress & Resilience Evaluation — CONDITIONAL, evidence-gated, business-criticality-aware. The top-down companion to SYNC:scale-technique-gate: instead of "is technique X present?", put the system UNDER concrete failure/load scenarios and judge whether it SURVIVES, SELF-HEALS, and whether its BUSINESS needs it to. ADVICE-ONLY: emit the Scenario Stress Matrix as guidance; NEVER mutate any score, verdict band, or gate pass/fail.

1. Reuse the scale tier derived by SYNC:scale-technique-gate (or derive it identically from evidence); also derive business-criticality B0–B3 from specs/SLA/product docs + the domain, cite file:line + confidence. B0 best-effort · B1 important · B2 business-critical · B3 mission-critical/regulated. Unknown → state the assumption, do NOT default to B3/T3. Criticality-signal floor (both-directions safety): regulated / PII / financial / health data, money movement, auth/identity, or legal-compliance scope raises B to at least B2 even absent SLA/SLO docs; anti-over-engineering lowers hardening ONLY when NO such signal is present. B (blast if it fails) and T (scale of load/data) are independent — a low-traffic payroll run is low-T, high-B.
2. Select in-scope scenarios — only those the system's B/T combination warrants (a B0 internal PoC skips region-loss/DR entirely; a B3/T0 regulated service still needs backups + DR by BUSINESS, not scale).
3. Walk each in-scope scenario: simulate the stimulus → trace the break path → name the failure signature → answer the self-heal/recovery question (auto-recover? MTTR? manual runbook?) → name the trade-off it forces. Families: traffic spike · sustained growth · data-volume growth · write/ingest burst · dependency down/slow · instance/node loss · zone/region loss · data loss/corruption · poison-message/retry-storm · cascading failure/backpressure · cold-start/deploy-blip · clock-skew/duplicate-delivery.
4. Assign one verdict per scenario: WITHSTANDS · DEGRADES-GRACEFULLY · FAILS-HARD (→ advise only) · N/A-by-business (not warranted → skip, not a gap) · OVER-HARDENED (resilience beyond business need → advise AGAINST, cite carrying cost).
5. Anti-over-engineering guard (first-class): a lean system whose business does not need HA/DR is a PASS; OVER-HARDENED flags resilience the business does not warrant. This guard is symmetric with the criticality-signal floor above — never under-harden a B2+ system just because its traffic is low.
6. Output — Scenario Stress Matrix: scenario | in-scope (B/T)? | verdict | self-heal | trade-off | evidence (file:line/config/infra). Full catalog + Business×Scale in-scope baseline + verdict/tier tables → .claude/docs/scenario-stress-catalog.md. ADVISORY-ONLY: NEVER mutate any /20, /24, verdict band, or gate pass/fail. Drift-guard: scenarios/verdicts/business-tiers are AUTHORITATIVE in the catalog — update it FIRST, then re-run .claude/scripts/inject_scenario_stress_gate.py. Scale tier stays single-sourced in scale-technique-catalog.md.

BLOCKED until: - [ ] scale tier + business-criticality (with criticality-signal floor) derived from evidence - [ ] in-scope scenarios selected - [ ] matrix emitted - [ ] over-hardening guard applied - [ ] advisory-only (no score/verdict mutation) confirmed

Goal Contract Satisfaction Loop — Persist the user goal in an external file, execute against it, and loop review/fix until every saved required criterion passes or a blocker escalates. Bounded closed loop — NEVER open-ended autonomous exploration.

1. Resolve the active goal (in order): active plan goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → create a new Goal Contract from the current user request (template: .claude/templates/goal-contract-template.md).
2. Required sections: Original Request, Purpose, Success Criteria (checkboxes; mark required vs optional), Constraints, Evidence Required, Iteration Log, Goal Satisfaction matrix.
3. Before work: read the active goal and map planned work to saved success criteria — execution serves the saved criteria, never chat memory alone.
4. After execution/verification: append an Iteration Log entry — result, evidence references (file:line, command output, report path), remaining gaps.
5. Review gate: emit a Goal Satisfaction matrix — | Success Criterion | Evidence | Status | with PASS/FAIL/BLOCKED. Overall PASS requires every required criterion PASS.
6. Loop rule (retry): required criterion FAIL → validate the gap is real → fix → re-review only the affected criteria. Stop cleanly when all required criteria PASS.
7. Escalation rule (stop): two consecutive iterations with no criterion progressing, or a blocker needing user input → mark the criterion BLOCKED with a user-facing reason and escalate. NEVER loop indefinitely.
8. Skip rule: tiny conversational tasks may skip the goal file ONLY with a recorded one-line reason. User-accepted gate skips are recorded in the goal file with reason and scope.
9. Security: NEVER store secrets, tokens, credentials, or private customer data in goal files — store evidence references and redact sensitive values.

Blocked until: active goal resolved (or skip reason recorded) · saved success criteria read before edits · iteration evidence appended after execution · Goal Satisfaction matrix emitted before any PASS verdict.

Trade-Off Interrogation Gate — ALWAYS ask these THREE questions before ANY verdict, score, finding, or recommendation — about the thing under review AND about every recommendation YOU make. — why: naming a benefit without its price is an endorsement, not a review; the costliest trade-offs are the ones nobody wrote down.

1. Is there any trade-off? Name what it SACRIFICES. "None" / "pure win" is an unfinished analysis, NOT an answer — to claim none, state which dimensions you checked and why each is unaffected: future change cost · complexity · performance/latency · memory/cost · coupling · reversibility · migration burden · operational load · blast radius · security posture · testability · team skill/ramp · delivery time · UX.
2. Is it worth it? Weigh gain against sacrifice EXPLICITLY — what is gained (with a metric) · what it costs · WHO pays · WHEN it comes due — then emit WORTH IT / NOT WORTH IT / UNCLEAR. "Better" with no metric and no cost FAILS this question. NOT WORTH IT → withdraw or replace the recommendation, never keep it as-is.
3. Is the trade-off material enough to CONFIRM WITH THE USER? A material trade-off is the user's call, never yours. MATERIAL when ANY holds: irreversible / one-way door (data migration, public contract, storage format, vendor lock-in) · cost shifted onto someone else (another team, ops/on-call, future maintainer, end user) · one quality attribute traded for another (correctness↔speed, security↔convenience, latency↔cost, simplicity↔flexibility) · a boundary crossed (client↔server tier, service contract, event contract, shared library) · a high-consequence path (auth, money, data integrity, breaking change, High/Medium residual risk) · the worth-it verdict is UNCLEAR.

MATERIAL → STOP and confirm by asking the user directly BEFORE the verdict stands — state the trade-off, both options, what each sacrifices, and your recommendation. NOT material → record it inline with a one-line justification and proceed.

Non-asking execution contexts — ESCALATE BY HANDOFF, never by silence. ask the user directly reaches only the main interactive agent: a sub-agent cannot ask the user, and a terminal/verdict-only mode asks nothing by design. When you are running in such a context, the obligation is redirected, never waived — do ALL of: (a) complete questions 1 and 2 normally; (b) decide materiality and record it in the Trade-Off Assessment row with confirmed? = NO — cannot ask from this context; (c) name the unconfirmed MATERIAL trade-off explicitly in your returned summary/verdict so the CALLER (or parent orchestrator) escalates it by asking the user directly on your behalf — a material trade-off mentioned only inside a report file on disk is NOT a handoff; (d) do not emit an unqualified PASS — mark the verdict as carrying an unconfirmed material trade-off, so the caller's gate stays closed until the user answers. The caller inherits the escalation duty the moment it reads your return.

This carve-out is about reachability, not convenience: it applies ONLY where the tool genuinely cannot reach the user (spawned sub-agent, terminal validate/verdict-only mode, non-interactive/headless run). It is NEVER a licence to skip the question, to self-approve a one-way door, or to downgrade materiality because asking is inconvenient — if you CAN ask, you MUST ask.

Emit a Trade-Off Assessment row per reviewed decision and per recommendation: | decision | sacrifices | gain (metric) | who pays, when | WORTH IT/NOT/UNCLEAR | material? | confirmed? |.

BLOCKED until: trade-off named (or dimensions-checked justification given) · worth-it verdict emitted · materiality decided · every MATERIAL trade-off either confirmed with the user OR — in a non-asking context — handed off in the returned verdict for the caller to confirm. A MATERIAL trade-off that is neither confirmed nor handed off can NEVER be PASS, and NEVER gets buried as a Low-severity

…(truncated)