hermes-skills/software-development/doc-review/SKILL.md

name, description, version, author, license, metadata

name	description	version	author	license	metadata
doc-review	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.	1.0.0	Hermes Agent (merged from Every Inc compound-engineering ce-doc-review)	MIT	hermes tags related_skills review planning quality-gate compound-engineering 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.

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:

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:

## 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