Initial commit: Hermes Agent Skills collection
This commit is contained in:
Debian
@@ -0,0 +1,196 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user