Architecture Review — Engineering Lens

Reviews plans or implementations for technical soundness. Produces mandatory mermaid diagrams, edge case analysis, and a scored verdict.

Before anything else: read $HOME/.agentic-workflow/toolkit/skills/_preamble.md and follow it (skill index, provider capability map, bootstrap check, session context). Run its Session Close section when this skill finishes.

Step 1: Resolve the Target

Parse flags first: --plan <path> (equivalent to the positional path), --output <path> (explicit output file — /autoplan passes --output <feature-dir>/arch-review.md), --slim (compact output: matrix, scores, and verdict only).

If a file path is given, read that file as the plan/spec to review.

If a directory is given and it is a plan dir, read plan.md + engineering.md + TASKS.md — the reader matrix in _shared/plan-layout.md. Legacy aliases per _shared/plan-layout.md: fall back to design.md (→ engineering.md) and requirements.md (→ product.md) only if the canonical file is absent. If it is a code directory, explore its structure by searching and reading files.

If nothing is given, try two fallbacks in order:

1. Auto-discover the most recent plan per _shared/plan-discovery.md:

   SHARED_DIR="$HOME/.agentic-workflow/toolkit/skills/_shared"
   source "$SHARED_DIR/repo-slug.sh"
   PLAN_DIR=$(ls -1dt "$AW_DIR/plans/"*/ 2>/dev/null | head -1)

   Resolve a found plan dir per the reader matrix above; a legacy single .md file is read as-is.
2. If no plans exist, review the current project's architecture by exploring the repository root.

Step 2: Read Context

Read all available architectural context:

• AGENTS.md (or CLAUDE.md if that is all the repo has) — project conventions and structure
• planning/ARCHITECTURE.md or ARCHITECTURE.md — existing architecture docs
• planning/ERD.md or ERD.md — data model
• planning/API_CONTRACT.md or API_CONTRACT.md — API surface
• README.md — project overview

Search files to discover these -- do not assume paths.

Step 3: Architecture Analysis

Spawn a subagent — one read-only explore agent (Claude Code: subagent_type: "Explore"; Codex/Cursor: an explorer/read-only agent type if available, else default), search breadth "very thorough" — with this prompt:

"Map the system at <target>. Read source files, configuration, and package manifests. Report, with file:line evidence for each: (1) component boundaries — a named list of distinct modules/services and where the boundaries are drawn; (2) dependency graph, including circular dependencies; (3) data flow paths — how data enters, transforms, exits; (4) external integrations; (5) state management — where state lives, how it syncs, source of truth; (6) error propagation across boundaries — handled or swallowed."

Output contract: the agent must return the named boundary list (it drives the Step 5 matrix rows) plus the six areas above. Fallback: if subagent spawning is unavailable or returns nothing usable, do the same exploration directly (search and read files yourself), producing the same named boundary list.

Step 4: Generate Mandatory Diagrams

Create three mermaid diagrams. These are mandatory -- the review is incomplete without them. Every diagram must satisfy two assertions:

• ≥3 nodes named after real components from Step 3 (actual module, file, service, or table names — e.g. cli.ts, ledger.db, decisions.sqlite)
• No placeholder labels — generic labels such as "Component A", "Service", "Input", "Transform", "Store" do not count; a diagram containing them is invalid and the review is incomplete.

4a: Component Diagram

Each module/service as a box with dependency arrows: internal components and responsibilities, external dependencies (databases, APIs, file system), direction of dependency.

4b: Data Flow Diagram

How data moves from entry to exit: input sources (user, API, file, event), transformation steps, storage points, output destinations.

4c: Sequence Diagram

The single most critical user flow end-to-end: all participants, request/response pairs, and the error path for the main flow.

Step 5: Edge Case Matrix

Build a boundary × failure-mode matrix — one row per component boundary from Step 3's named list, one column per failure mode. Every cell is either a finding id (defined below the table) or OK — <evidence> (file:line, config value, or plan-line proving the case is handled). No blank cells — an unexamined cell is itself a finding. One covered boundary must never masquerade as full coverage.

Boundary	Dependency unavailable	Invalid/malicious input	Load 10x	State leakage
{boundary 1}	F1 or OK — <evidence>	…	…	…
{…one row per Step-3 boundary…}

Failure-mode definitions:

• Dependency unavailable — timeout? retry? fallback? does the failure cascade or is it contained?
• Invalid / malicious input — unexpected types, missing fields, oversized payloads; validation at the boundary or deep inside; injection vectors (SQL, command, path traversal)?
• Load 10x — first bottleneck (CPU, memory, I/O, connections); unbounded queues, caches, buffers?
• State leakage — cross-request/user leakage; shared mutable globals; guaranteed cleanup (connections, file handles, temp files)?

Findings (F1, F2, …): severity per _shared/severity.md, description, location, concrete mitigation.

Step 5.5: Review Self-Check

Verify your own evidence: for every OK — <evidence> cell in the matrix, confirm the cited code actually exists by searching and reading it (grep the named timeout, validator, handler, or config key). Downgrade any cell whose evidence does not hold to a finding.

Optional adversarial delegation: per _shared/dark-factory.md (archReview review-gap objective template) — gate-checked there; skip silently when not enabled. Incorporate delegated findings into the matrix and Top Risks before writing the verdict.

Step 6: Review Verdict

Produce the final assessment. The verdict is rule-derived from the matrix findings and scores (anchored 1–5 scale per _shared/severity.md):

• any CRITICAL finding, or any dimension scored 1 ⇒ REDESIGN
• any HIGH finding, or any dimension scored ≤2 ⇒ NEEDS WORK
• otherwise ⇒ SOUND

# Architecture Review: {title}

_Reviewed by `/archReview` on {ISO date}_

## Verdict: {SOUND | NEEDS WORK | REDESIGN}

{One paragraph justification citing the finding ids / dimension scores that drove it}

## Scores

_Anchored 1–5 scale from `_shared/severity.md` (5 = no findings above LOW … 1 = CRITICAL or unaddressed)._

| Dimension | Score (1–5) | Notes |
|-----------|:---:|-------|
| Complexity | {n} | {brief justification} |
| Scalability | {n} | {brief justification} |
| Maintainability | {n} | {brief justification} |

## Component Diagram

{mermaid diagram from 4a}

## Data Flow Diagram

{mermaid diagram from 4b}

## Sequence Diagram

{mermaid diagram from 4c}

## Top Risks

| # | Risk | Impact | Likelihood | Mitigation |
|---|------|--------|------------|------------|
| 1 | {risk} | {high/med/low} | {high/med/low} | {recommendation} |
| 2 | {risk} | {high/med/low} | {high/med/low} | {recommendation} |
| ... | ... | ... | ... | ... |

## Edge Case Matrix

{the Step 5 boundary × failure-mode matrix, followed by its findings list — empty findings list is the literal `None.`}

## Missing Error Handling
- {specific location and what's missing}
- {specific location and what's missing}

## Suggested Improvements (Prioritized)

_Severity per `_shared/severity.md` (legacy P0→CRITICAL, P1→HIGH)._

| Severity | Improvement | Effort | Impact |
|----------|------------|--------|--------|
| CRITICAL | {must fix before shipping} | {S/M/L} | {description} |
| HIGH | {should fix soon} | {S/M/L} | {description} |
| MEDIUM/LOW | {nice to have} | {S/M/L} | {description} |

End the file with the normalized final line per _shared/severity.md (CD9 mapping: SOUND→PASS, NEEDS WORK→NEEDS_WORK, REDESIGN→BLOCKED):

verdict: <PASS|NEEDS_WORK|BLOCKED>

Step 7: Write the Review

If --output <path> was provided, write to that exact path (ensure the parent dir exists with mkdir -p). Otherwise generate a URL-safe slug from the target title (lowercase, hyphens, no special chars) and write to the default path:

SHARED_DIR="$HOME/.agentic-workflow/toolkit/skills/_shared"
source "$SHARED_DIR/repo-slug.sh"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)

Default: $AW_DIR/plans/{timestamp}-arch-review-{slug}.md

Include all three mermaid diagrams and the complete analysis.

Step 8: Report

Show a summary to the user:

Architecture Review complete!

Verdict: {SOUND | NEEDS WORK | REDESIGN} (normalized: {PASS | NEEDS_WORK | BLOCKED})

Scores:
  Complexity:      {n}/5
  Scalability:     {n}/5
  Maintainability: {n}/5

Review written to: {resolved output path}

Top 3 risks:
  1. {risk summary}
  2. {risk summary}
  3. {risk summary}

Suggested next steps:
  /productReview — Get founder-lens feedback on the plan
  /officeHours — Brainstorm solutions to identified risks

Next steps

• /autoplan — run alongside other plan-review lenses in parallel
• /review — deep code review of the implementation