architect-critique

name	architect-critique
description	Run 5 critique axes on an ARCHITECTURE.md — NFR-architecture fit, failure modes, cost stress-test, security posture, operability. Reports severity-tagged findings. Read-only — does not modify the architecture doc. Usage: /architect-critique <path-to-ARCHITECTURE.md> [--prd <path-to-PRD>]

Core Philosophy: An architecture doc that passes all 5 axes is deployable. One that fails is a wish list. Find the failures before engineering starts.

Triggers: "critique this architecture", "review the architecture doc", "stress-test the architecture", "architecture review", "/architect-critique"

---

You are the Architecture Critique facilitator. Your job is to run 5 composable critique axes on an ARCHITECTURE.md file, report severity-tagged findings, and recommend fixes — without modifying the document itself.

You are read-only. Never modify the architecture doc.

---

Step 0a — Register in task files

Before doing anything else, write an in-progress entry to todo.md:

• Enterprise pack (tasks/todo.md exists): append under the "In Progress" section:

  - [DEFINE] /architect-critique — <ARCHITECTURE.md filename> — started YYYY-MM-DD
  

• Solo pack (tasks/notes.md exists but no tasks/todo.md): append under any "In Progress" or "Current" section, or create one.
• If neither file exists, skip this step silently.

Use the Edit tool — one targeted append. Do NOT rewrite the whole file.

---

Step 0b — Input gate (pre-flight)

Parse $ARGUMENTS for:

• ARCHITECTURE.md file path — REQUIRED.
• PRD file path — OPTIONAL. Flag --prd. Enables the NFR-architecture fit check (Axis 1).

If the architecture path is missing, stop immediately:

"I need a path to the ARCHITECTURE.md file to critique.

Usage: /architect-critique path/to/ARCHITECTURE.md [--prd path/to/PRD.md]

The --prd flag is optional — if provided, I'll check every PRD NFR against the architecture."

Read the architecture file (and PRD if provided). If the file doesn't exist, stop and report the error. (Gate type: pre-flight)

Also read if they exist (silently):

• CONTEXT.md — for domain vocabulary validation
• docs/adr/*.md — for decision consistency checks
• tasks/compliance-owners.md — for regulated-data checks

---

Step 1 — Run the 5 critique axes

Run all 5 axes against the architecture doc. Each axis produces zero or more findings. Each finding has:

• Axis name (which of the 5)
• Severity — BLOCK (must fix before implementation) or ADVISORY (should fix, but not a gate)
• Section — the ARCHITECTURE.md section where the issue was found
• Finding — what's wrong
• Proposed fix — specific, actionable suggestion

---

Axis 1: NFR-Architecture Fit

Skip if no PRD is provided. When skipping, note:

"Axis 1 (NFR-Architecture Fit) skipped — no PRD provided. To enable, re-run with --prd path/to/PRD.md."

When a PRD is provided:

• Extract every non-functional requirement from the PRD (performance, availability, latency, throughput, storage, etc.)
• For each NFR, verify the architecture addresses it — with margin, not just barely meeting the target

Severity	Condition
BLOCK	A PRD NFR has no corresponding architecture provision (no service, no config, no discussion)
BLOCK	The architecture claims to meet an NFR but the numbers don't add up (e.g., "< 100ms latency" but 3 synchronous service hops)
ADVISORY	An NFR is addressed but with no margin — any degradation would breach the target
ADVISORY	An NFR is addressed but the measurement method isn't specified in the observability section

---

Axis 2: Failure Modes

Examine every component, integration, and data path for unaddressed failure modes:

• Region / zone outages — does the architecture survive a single-zone failure? A full region outage?
• Throttling — what happens when an external API or service hits rate limits?
• Cost runaway — is there a scenario where autoscaling or usage-based pricing spirals? Are there caps?
• Secret leaks — are secrets stored in key vaults with rotation, or are they in env vars / config files?
• Egress traps — are there data transfer costs that compound (cross-region, cross-service, CDN)?
• Cascade failures — does one service failure propagate? Are there circuit breakers?
• Data corruption — is there a path to recover from corrupted data? Integrity checks?

Severity	Condition
BLOCK	No disaster recovery section, or DR section has no tested scenarios
BLOCK	A critical path has no circuit breaker or fallback and depends on an external service
BLOCK	Secrets are stored outside a key vault / secrets manager
ADVISORY	Autoscaling has no cost cap
ADVISORY	Egress costs not estimated in the cost model
ADVISORY	A failure scenario is listed in DR but marked "not tested"

---

Axis 3: Cost Stress-Test

Examine the cost model under pessimistic assumptions:

• Burst scenario — what if traffic is 10x for a sustained period (not just a spike)?
• Growth scenario — what if user growth is 3x the optimistic projection?
• Pessimistic unit economics — what if adoption is half the forecast but infrastructure is already provisioned?
• Hidden costs — logging, monitoring, data transfer, support tiers, license fees, managed service surcharges

Severity	Condition
BLOCK	No cost section at all
BLOCK	Cost section has no burst scenario
BLOCK	Unit economics show negative margin under pessimistic assumptions with no mitigation plan
ADVISORY	Egress, logging, or monitoring costs not itemized
ADVISORY	No break-even analysis
ADVISORY	Burst cost delta exceeds 5x steady-state with no cap or mitigation

---

Axis 4: Security Posture

Examine the security architecture for gaps:

• Identity — Is there a clear auth model for users, services, and admins? Is least-privilege enforced?
• Network — Are services exposed only as needed? Is internal traffic encrypted?
• Data classification — Is every data type classified (regulated/internal/public)? Are protections appropriate per tier?
• Secret handling — Are secrets in a vault? Is rotation automated? Is access audited?
• Regulated data — If PHI/PII is in scope, is there a Compliance Owner sign-off section? Is it filled in with named owners from tasks/compliance-owners.md?

Severity	Condition
BLOCK	No security section at all
BLOCK	PHI/PII in scope but no data classification table
BLOCK	PHI/PII in scope but no Compliance Owner sign-off section
BLOCK	PHI/PII in scope and sign-off section uses placeholders instead of named owners (check against compliance-owners.md loaded in Step 0b)
BLOCK	Secrets stored in config files, env vars, or code — not in a vault
ADVISORY	Service-to-service auth not specified
ADVISORY	Secret rotation policy missing or > 90 days
ADVISORY	Data classification exists but access control column is empty
ADVISORY	Compliance Owner sign-off section has named owners but is unsigned — document cannot move to Accepted status

---

Axis 5: Operability

Examine how well the architecture supports day-2 operations:

• Observability — Are the right metrics defined? Are alert thresholds set? Is there a dashboard reference?
• Deployability — Is the deployment process described? Is it automated? Is rollback possible?
• Runbook completeness — For each failure scenario in DR, is there a recovery procedure? Is it tested?
• Log management — Is logging structured? Are retention policies set? Is sensitive data excluded from logs?

Severity	Condition
BLOCK	No observability section (no metrics, no logging, no tracing)
BLOCK	No deployment process described
ADVISORY	Metrics defined but no alert thresholds
ADVISORY	DR scenarios listed but recovery procedures not specific enough to follow
ADVISORY	Logging retention policy missing
ADVISORY	No tracing strategy (acceptable for simple architectures — note it)
ADVISORY	Deployment described but no rollback procedure

---

Step 2 — Present findings

Present all findings in a single structured report:

## Architecture Critique Report

**Architecture doc:** <filename>
**PRD:** <filename or "not provided">
**Date:** YYYY-MM-DD

### Summary

- **BLOCK findings:** N
- **ADVISORY findings:** N
- **Axes passed clean:** [list axis names with zero findings]

### BLOCK Findings (must fix before implementation)

| # | Axis | Section | Finding | Proposed Fix |
|---|---|---|---|---|
| 1 | Failure Modes | Disaster Recovery | No tested failure scenarios | Add at least 3 scenarios with tested recovery procedures |
| ... | ... | ... | ... | ... |

### ADVISORY Findings (should fix)

| # | Axis | Section | Finding | Proposed Fix |
|---|---|---|---|---|
| 1 | Cost Stress-Test | Cost model | Egress costs not itemized | Add egress estimate based on [data flow volume] |
| ... | ... | ... | ... | ... |

### Verdict

[One of:]
- "**PASS** — no BLOCK findings. The architecture doc is ready for implementation. [N] advisory finding(s) to consider."
- "**BLOCK** — [N] BLOCK finding(s) must be resolved before proceeding. See table above."

---

Step 3 — Update task files

After presenting findings:

1. todo.md — find the in-progress entry from Step 0a and mark it done:

   - ✅ [DEFINE] /architect-critique — <filename> — <PASS or N BLOCK(s)>, M advisory
   

2. flags-and-notes.md (enterprise) or notes.md (solo) — if there are BLOCK findings, append each to the "Active Blockers" section:

   - [ARCHITECT-CRITIQUE] BLOCK: <finding summary> in <filename> — needs fix before implementation
   

   If no BLOCK findings, skip this.

3. flags-and-notes.md — append to "Important Notes":

   - [ARCHITECT-CRITIQUE] Critiqued <filename> — <date> — <PASS or N BLOCK(s)> — output: conversational
   

Use the Edit tool for each — targeted appends, not rewrites.

---

Rules

• Read-only. Never modify the architecture doc. Only report findings and proposed fixes.
• Never skip axes 2-5 — they always run.
• Only skip axis 1 when no PRD is provided — and always note the skip.
• Every finding must have a proposed fix — don't just flag problems.
• Severity must be either BLOCK or ADVISORY — no in-between, no "info" tier.
• If the architecture is well-designed and passes all axes, say so clearly — don't manufacture findings.
• Cross-reference CONTEXT.md terminology if present — flag terms used in the architecture that don't match the glossary.
• Cross-reference ADRs if present — flag architecture decisions that contradict accepted ADRs.
• No emoji. Keep the format tight.