---
name: doc-review
description: "Review requirements, plans, or specs with role-specific lenses before implementation. Use when the user wants to improve an existing planning document — catches scope creep, feasibility issues, and missing requirements before code is written."
version: 1.0.0
author: Hermes Agent (merged from Every Inc compound-engineering ce-doc-review)
license: MIT
metadata:
  hermes:
    tags: [review, planning, quality-gate, compound-engineering]
    related_skills: [brainstorming, plan, writing-plans, requesting-code-review]
---

# Document Review

Review requirements or plan documents through multi-persona analysis before implementation begins. Catches issues when they're cheapest to fix — before code is written.

**Core principle:** A bug in a plan costs minutes to fix. A bug in code costs hours. Review plans with the same rigor as code.

## When to Use

- After writing a design doc or plan, before implementation
- When reviewing someone else's plan or spec
- Before handing a plan to `subagent-driven-development`
- When a plan feels "too big" or "unclear"

**Skip for:** trivial plans (single-file change), informal notes, already-reviewed plans.

## The Process

### Phase 1: Get and Analyze Document

Read the document. If no path given, check:
- `.hermes/plans/` for the most recent plan
- `docs/superpowers/specs/` for design docs
- `docs/plans/` for legacy plans

### Phase 2: Classify Document Type

Classify by content shape, not file path:

| Type | Signals | Review Focus |
|---|---|---|
| **Requirements** | Actors, flows, acceptance examples, scope boundaries | Is the WHAT well-defined? |
| **Plan** | Implementation units, file paths, test scenarios, sequencing | Is the HOW sound? |
| **Spec** | Mixed — has both requirements and implementation | Both dimensions |

Pass the classification to each reviewer so they adapt their lens.

### Phase 3: Select Reviewer Personas

Based on the document content, activate relevant reviewers:

**Always-on:**
- **Coherence Reviewer** — Internal consistency, logical flow, no contradictions
- **Feasibility Reviewer** — Can this actually be built with the stated approach?

**Conditional (activate based on content):**

| Persona | Activate When | Focus |
|---|---|---|
| **Scope Guardian** | >8 requirements, multiple priority tiers, stretch goals | Scope creep, goal-requirement alignment |
| **Security Lens** | Auth, API endpoints, PII, payments, credentials | Security requirements coverage |
| **Design Lens** | UI/UX references, user flows, interaction descriptions | UX completeness, accessibility |
| **Adversarial Reviewer** | High-stakes domain, new architecture, unvalidated premises | Challenge assumptions, find blind spots |
| **Product Lens** | Strategic claims, prioritization decisions | Market fit, opportunity cost |

### Phase 4: Dispatch Reviewers

Dispatch each reviewer as a `delegate_task` subagent. Each gets the full document text and the classification.

```python
delegate_task(
    goal=f"""You are a {persona_name}. Review this {doc_type} document.

Focus on: {persona_focus_questions}

Document:
---
{document_content}
---

Return findings as:
- Finding: [description]
- Severity: critical|important|minor
- Section: [where in the doc]
- Suggestion: [specific improvement]
""",
    context=f"Document review as {persona_name}",
    toolsets=['file']
)
```

For parallel review, use batch mode:

```python
delegate_task(tasks=[
    {"goal": "Coherence review of...", "context": "..."},
    {"goal": "Feasibility review of...", "context": "..."},
    {"goal": "Scope guardian review of...", "context": "..."},
])
```

### Phase 5: Aggregate and Present

Merge all findings. Group by severity:

**Critical** — Must fix before implementation:
- Contradictions between sections
- Missing requirements for stated goals
- Infeasible approaches
- Security gaps in security-sensitive plans

**Important** — Should fix:
- Unclear acceptance criteria
- Missing edge cases
- Weak test scenarios
- Ambiguous scope boundaries

**Minor** — Nice to fix:
- Formatting issues
- Missing cross-references
- Style suggestions

Present as a structured report:

```markdown
## Document Review: [doc name]

**Classification:** [requirements|plan|spec]
**Reviewers:** [list of active personas]

### Critical Findings
1. [Finding] — [Section] — [Suggestion]
...

### Important Findings
1. [Finding] — [Section] — [Suggestion]
...

### Minor Findings
1. [Finding] — [Section] — [Suggestion]
...

### Verdict
[READY FOR IMPLEMENTATION | NEEDS REVISION | MAJOR REWORK]
```

### Phase 6: Auto-Fix Safe Improvements

Some findings can be auto-fixed in the document:
- Typos and formatting
- Missing cross-references
- Adding a "non-goals" section if scope is implicit
- Clarifying ambiguous terms

Apply safe fixes with `patch` tool. Present non-safe findings for user decision.

## Interaction Mode

### Interactive (default)
Present findings, walk through critical/important ones one at a time, offer to fix.

### Headless (for pipeline use)
Return structured findings without blocking. Caller decides what to fix.

## Pitfalls

- **Don't review code in the plan** — if the plan has full code, that's a plan smell
- **Don't skip adversarial review for high-stakes plans** — it's the most valuable reviewer
- **Don't classify by path** — a requirements doc in `docs/plans/` is still requirements
- **Don't activate all personas for every doc** — match personas to content
- **Don't auto-fix critical findings** — they need human judgment

## Integration with Other Skills

- **brainstorming** — review the design doc before transitioning to planning
- **plan / writing-plans** — review the plan before handing to subagent-driven-development
- **requesting-code-review** — this is the pre-implementation counterpart

## Hermes Agent Integration

- `read_file` — read the document
- `search_files` — find related docs for cross-referencing
- `delegate_task` — dispatch persona reviewers in parallel
- `patch` — apply safe auto-fixes to the document
- `write_file` — save the review report

## Remember

```
Review plans like code
Match personas to content
Critical findings block implementation
Safe fixes auto-apply, risky ones need human judgment
The cheapest bug is the one you catch before writing code
```