architecture-peer-review

What this skill does

# Architecture Peer Review Skill

## Purpose

This skill acts as a **Solution Architect peer reviewer** for ARCHITECTURE.md documents. It evaluates design decisions, questions trade-offs, identifies risks, and assesses real-world viability — the kind of review a senior architect would give in a design review meeting.

The output is an **interactive HTML playground** (via the `playground` plugin) where the user triages findings, approves or rejects each one, adds comments, and copies a fix prompt back to Claude.

**Distinct from** the `architecture-docs` skill's REVIEW_AUDIT_WORKFLOW: that workflow validates form compliance (structure, template adherence). This skill provides opinionated architectural judgment on quality, soundness, and production-readiness.

---

## When to Invoke This Skill

- User asks to "peer review", "review architecture", "critique architecture", or "assess architecture quality"
- User asks for "architecture feedback", "design review", or "architecture assessment"
- User wants a second opinion on their ARCHITECTURE.md
- User asks for scalability, security, or performance review of their architecture
- User uses `/skill architecture-peer-review`
- User asks to "regenerate peer review playground", "rebuild review playground", or "reload peer review results" — activates the **fast path** (Step 0) to regenerate from saved JSON without re-running agents

**Do NOT invoke for:**
- Form/template compliance validation → use `architecture-docs` skill (REVIEW_AUDIT_WORKFLOW)
- Compliance contract generation → use `architecture-compliance` skill
- Creating or editing ARCHITECTURE.md → use `architecture-docs` skill
- Business requirements review → use `architecture-readiness` skill
- Component index updates → use `architecture-component-guardian` skill

---

## Files in This Skill

| File | Purpose |
|------|---------|
| `SKILL.md` | This file — entry point and workflow |
| `PEER_REVIEW_CRITERIA.md` | All review checks organized by depth level and category (82 checks across 13 categories) |
| `PLAYGROUND_TEMPLATE.md` | Custom playground template for the interactive review HTML file |
| `agents/reviewers/peer-review-category-agent.md` | Universal category reviewer sub-agent — evaluates one category's checks in parallel |

---

## Workflow

### Step 0 — Check for Existing Review Data (Fast Path)

Before starting a full review, check if the user explicitly requested regeneration from existing data (e.g., "regenerate playground", "rebuild review playground", "reload peer review results").

**If the user requested regeneration:**

1. Glob for `architecture-peer-review-*.json` in the project root.
2. If found, present the most recent file(s) with dates and let the user pick one.
3. Read the selected JSON file and parse it as `reviewData`.
4. **Validate** the JSON contains: `findings` (array), `scorecard` (object with `overall`, `rating`, `categories`), and `depthLevel` (string).
5. **Staleness check**: if the JSON contains `metadata.sourceFiles`, compare each file's `lastModified` timestamp against the current file modification time. If any source file has been modified since the review, warn:
   ```
   ⚠️ Source files changed since this review was saved:
     - docs/07-security-architecture.md (modified 2026-04-05, review from 2026-04-03)
   Results may be stale. Proceed with regeneration or run a fresh review?
   ```
6. If the user confirms, **skip directly to Step 7** (Generate Interactive Playground) using the loaded `reviewData`.
7. Report: `♻️ Regenerated playground from saved results (skipped agent evaluation)`

**If no JSON files found**: inform the user and proceed with the full review workflow (Step 1).

**If the user did NOT request regeneration**: proceed normally to Step 1.

---

### Step 1 — Locate Architecture Document

Search for `ARCHITECTURE.md` at the project root.

**Multi-file structure detected** if `ARCHITECTURE.md` exists as a navigation index and a `docs/` directory contains numbered section files. In this case, the full architecture spans:
- `ARCHITECTURE.md` (navigation index)
- `docs/NN-section-name.md` files (one per section)
- `docs/components/NN-component-name.md` files (or `docs/components/<system>/NN-*.md` for multi-system architectures)
- `adr/*.md` files (for Hard depth)

**Monolithic structure**: A single `ARCHITECTURE.md` file contains all 13 sections.

If no `ARCHITECTURE.md` is found, abort with: *"No ARCHITECTURE.md found. Use `/skill architecture-docs` to create one first."*

---

### Step 2 — Select Review Depth (BLOCKING — user must choose)

Present the three options. **Do not default or assume.** If the user says "review my architecture" without specifying depth, ask.

---

**Choose review depth:**

**Light** (~40 sec)
Structural check: are all required sections present? Do naming conventions follow standards? Are required fields populated?
- Checks: STRUCT (5), NAMING (5), SECTIONS (12) = 22 checks — 3 parallel agents

**Medium** (~90 sec)
Everything in Light plus content quality: are sections internally consistent? Do technology choices make sense together? Are integration patterns sound? Are metrics realistic?
- Checks: Light + COHERENCE (7), TECH (5), INTEG (5), METRICS (5) = 44 checks — 7 parallel agents

**Hard** (~2-3 min)
Everything in Medium plus deep architectural analysis: scalability design, security posture, performance patterns, operational readiness, ADR quality, trade-off honesty, TOGAF/BIAN alignment.
- Checks: Medium + SCALE (7), SECURITY (9), PERF (5), OPS (7), ADR (5), TRADEOFF (5) = 82 checks — 13 parallel agents

---

### Step 3 — Load Review Criteria

Read `PEER_REVIEW_CRITERIA.md`. Parse it into per-category blocks — one block per category, containing that category's full markdown criteria table (header row + all check rows).

Active categories for each depth are defined by the **Depth Level** column in the Scoring Weights table in `PEER_REVIEW_CRITERIA.md`.

Store for each active category:
- `code` — e.g., `SECURITY`
- `name` — e.g., `Security Posture`
- `weight` — as defined in the Scoring Weights table
- `checks_table` — the full markdown table text for that category (to be passed to the sub-agent)

---

### Step 4 — Resolve Architecture File List

Determine the ordered list of files to review (`doc_files`). This list is passed to each category agent — agents read the files themselves.

**File discovery order** (same for monolithic and multi-file):
1. `ARCHITECTURE.md` (always)
2. `docs/NN-*.md` files in numeric order (if `docs/` exists)
3. `docs/components/NN-*.md` and `docs/components/*/NN-*.md` files in numeric order (for Medium and Hard depth)
4. `adr/*.md` files in alphabetic order (for Hard depth only)

Store the result as `doc_files` — an ordered list of **absolute file paths**.

---

### Step 5 — Perform Review (Parallel Category Agents)

Spawn one `peer-review-category-agent` per active category. Issue Task() calls in **batches of 2 per message** (strict parallel barrier).

**Batching rule**: dispatch exactly **2 Task() calls per message**. After sending a batch, wait for BOTH `CATEGORY_REVIEW_RESULT:` blocks to return before sending the next batch. Do not start batch N+1 until every Task() in batch N has returned. If any category agent in a batch fails, record the failure and continue with the next batch (do not retry inline; failures are collected and reported at the end). This caps peak parallelism at 2 and gives the orchestrator a chance to observe early failures before dispatching the remaining batches. For Light (3 categories) this is 2 batches (2+1); Medium (7) is 4 batches (2+2+2+1); Hard (13) is 7 batches (2×6 + 1).

All agents use: `sa-skills:peer-review-category-agent`

**Agent prompt template:**
```
Review category.
category_code: [CODE]
category_name: [Name]
weight: [0.XX]
depth_level: [light|medium|hard]

CHECKS:
[paste the full markdown criteria table for this category]

FILES:
[absolute path 1]
[absolute path 2]
...
```

Pass all file paths from `do