my-review-docs

name	my-review-docs
description	Use when planning docs need review before implementation — dispatches all agent personalities (skeptic, believer, architect, security) against docs in parallel, aggregates findings by priority. Also use for "review the docs", "check planning docs", or "doc review".
argument-hint	< phase or area to focus on | (no arg: all docs) >
allowed-tools	Read, Write, Glob, Grep, Agent

Review Docs

Announce at start: "I'm using the my-review-docs skill to run all agents against the project docs."

Why This Skill Exists

Planning docs accumulate assumptions. Each agent sees the same docs through a different lens — the Architect sees missing schema decisions, the Security Reviewer sees undefined auth boundaries, the Platform Engineer sees no backup plan, the Frontend Engineer sees no performance budget. Running them all in parallel surfaces gaps that no single reviewer catches.

Rule: Run this skill before starting any new implementation phase, and whenever a planning doc is significantly updated.

---

Step 0: Resolve Project Root

Before any file operations, resolve the git repo root. All project-relative paths (docs/) are relative to this root, NOT pwd.

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

Step 1: Discover the docs

Scan the project for all planning and build documentation:

docs/build/          — phase docs, implementation plans, tracking
docs/planning/       — architecture, schema, tech stack, key decisions
docs/               — any .md files at root level

List every file found. Note which are missing from the expected set.

---

Step 2: Dispatch parallel review agents

Dispatch FIVE agents in parallel. Each agent reads the applicable agent personality file first, then reviews all relevant docs.

Agent 1 — Architect Review

• Load identity: ~/.claude/agents/specialists/architect.md
• Read all docs in docs/planning/ and docs/build/
• Apply the ## Planning Doc Review section: find data model gaps, undefined service boundaries, premature abstractions, unresolved cardinality decisions, missing migration strategy
• Return: structured findings in the Architect output format, focusing on the ## Planning Doc Infrastructure Gaps table

Agent 2 — Security Review

• Load identity: ~/.claude/agents/reviewers/security.md
• Read all docs in docs/planning/ and docs/build/
• Apply the ## Planning Doc Review section: find undefined auth models, missing tenant isolation statements, webhook security gaps, rate limiting absences, PII handling gaps
• Return: structured findings in Security Reviewer output format, Critical/High/Medium

Agent 3 — Platform Engineer Review

• Load identity: ~/.claude/agents/specialists/platform.md
• Read all docs in docs/planning/ and docs/build/
• Apply the ## Planning Doc Infrastructure Gaps section: find missing backup strategy, undefined DR plan, cron durability gaps, unbounded storage growth, missing monitoring plan
• Return: structured findings in Platform Engineer output format

Agent 4 — Frontend Engineer Review

• Load identity: ~/.claude/agents/specialists/frontend.md
• Read all docs in docs/planning/ and docs/build/
• Apply the ## Planning Doc Frontend Gaps section: find missing rendering strategy decisions, undefined performance budget, no image strategy, no font plan, undefined caching strategy
• Return: structured findings in Frontend Engineer output format

Agent 5 — Code Reviewer (Implementation Plan Review)

• Load identity: ~/.claude/agents/reviewers/code.md
• Read all docs in docs/build/ (phase docs and implementation plans)
• Apply the ## Planning Doc Review section: find undefined error states, missing rollback plans, implicit task ordering dependencies, untestable requirements, missing LOC estimates, undefined test strategy
• Return: findings as a flat list with severity (BLOCK / WARN / NOTE) per finding

---

Step 3: Aggregate findings

Collect all findings from all 5 agents. Build a unified findings table:

| # | Finding | Agent | Severity | Phase | Action |
|---|---------|-------|----------|-------|--------|

Severity levels:

• CRITICAL — blocks implementation; must be resolved before starting the affected phase
• HIGH — fix before launch; will cause production issues if not addressed
• MEDIUM — fix before scale; acceptable for MVP but will cause pain later
• LOW — log as tech debt; acceptable risk

---

Step 4: Write the report

Write the report to docs/build/review-report-YYYY-MM-DD.md using this structure:

# Doc Review Report — [date]

> Generated by /my-review-docs. Run all agents against project planning and build docs.

## Summary
- Docs reviewed: [list]
- Total findings: [N] critical, [N] high, [N] medium, [N] low
- Phases at risk: [list phases with critical/high findings]

---

## Critical Findings (block implementation)

[Grouped by phase. Each finding: agent that found it, description, what must be resolved]

---

## High Findings (fix before launch)

[Same format]

---

## Medium Findings (fix before scale)

[Same format]

---

## Low Findings (log as tech debt)

[Same format]

---

## Per-Agent Summaries

### Architect
[Full architect report]

### Security Reviewer
[Full security report]

### Platform Engineer
[Full platform report]

### Frontend Engineer
[Full frontend report]

### Code Reviewer (Implementation Plans)
[Full code reviewer report]

---

## Recommended Actions Before Next Phase

[Numbered list of the top 5 actions, each with: what to do, who owns it (which doc to update or which task to add), deadline (before phase N starts)]

---

Step 5: Print summary

Output:

1. Number of critical/high/medium/low findings
2. Top 3 critical findings with one-line descriptions
3. Phases that cannot start until findings are resolved
4. Path to the written report

---

Notes

• This skill is read-only — it never modifies planning docs. It only writes the review report.
• If docs/build/acceptance-criteria.md does not exist, note it prominently in the report and recommend running /my-create-acceptance-criteria before any implementation.
• The Skeptic/Believer/Referee debate agents are not dispatched here — they are for disputed decisions, not doc review. If an agent finding is contested, run the debate sequence separately.
• If the user passes a specific focus (e.g., "security only"), dispatch only the relevant agent and skip the others.

Gotchas

• Running without docs/ directory returns empty results — verify docs exist first
• Agent personalities may flag the same issue differently — dedup findings before presenting

Quick Help

What: Dispatches 5 agent personalities to review planning and build docs, then aggregates findings by priority. Usage:

• /my-review-docs — review all docs
• /my-review-docs phase-4 — focus on specific phase
• /my-review-docs security only — dispatch only security reviewer Output: docs/build/review-report-YYYY-MM-DD.md with critical/high/medium/low findings. When: Before any implementation phase or after major doc updates.