197 lines
6.2 KiB
Markdown
197 lines
6.2 KiB
Markdown
---
|
|
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
|
|
```
|