feat(skills): add document-review skill for brainstorm/plan refinement (#112)
Add optional review and refine step to workflows:brainstorm and workflows:plan that checks documents for clarity, completeness, user intent, and YAGNI. - New document-review skill with review questions and evaluation criteria - Brainstorm Phase 4 offers "Review and refine" option - Plan post-generation offers "Review and refine" after technical review - Includes YAGNI-based simplification guidance - Max 2 iteration rounds before suggesting to proceed Co-authored-by: Kieran Klaassen <kieranklaassen@users.noreply.github.com>
This commit is contained in:
Trevin Chow
@@ -94,7 +94,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
|
||||
| `/create-agent-skill` | Create or edit Claude Code skills |
|
||||
| `/generate_command` | Generate new slash commands |
|
||||
| `/heal-skill` | Fix skill documentation issues |
|
||||
| `/plan_review` | Multi-agent plan review in parallel |
|
||||
| `/technical_review` | Multi-agent technical/architecture review in parallel |
|
||||
| `/report-bug` | Report a bug in the plugin |
|
||||
| `/reproduce-bug` | Reproduce bugs using logs and console |
|
||||
| `/resolve_parallel` | Resolve TODO comments in parallel |
|
||||
@@ -129,7 +129,8 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `brainstorming` | Guided ideation for exploring requirements and approaches |
|
||||
| `brainstorming` | Explore requirements and approaches through collaborative dialogue |
|
||||
| `document-review` | Improve documents through structured self-review |
|
||||
| `every-style-editor` | Review copy for Every's style guide compliance |
|
||||
| `file-todos` | File-based todo tracking system |
|
||||
| `git-worktree` | Manage Git worktrees for parallel development |
|
||||
|
||||
@@ -480,14 +480,14 @@ After writing the enhanced plan, use the **AskUserQuestion tool** to present the
|
||||
|
||||
**Options:**
|
||||
1. **View diff** - Show what was added/changed
|
||||
2. **Run `/plan_review`** - Get feedback from reviewers on enhanced plan
|
||||
2. **Run `/technical_review`** - Get feedback from reviewers on enhanced plan
|
||||
3. **Start `/workflows:work`** - Begin implementing this enhanced plan
|
||||
4. **Deepen further** - Run another round of research on specific sections
|
||||
5. **Revert** - Restore original plan (if backup exists)
|
||||
|
||||
Based on selection:
|
||||
- **View diff** → Run `git diff [plan_path]` or show before/after
|
||||
- **`/plan_review`** → Call the /plan_review command with the plan file path
|
||||
- **`/technical_review`** → Call the /technical_review command with the plan file path
|
||||
- **`/workflows:work`** → Call the /workflows:work command with the plan file path
|
||||
- **Deepen further** → Ask which sections need more research, then re-run those agents
|
||||
- **Revert** → Restore from git or backup
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
name: plan_review
|
||||
description: Have multiple specialized agents review a plan in parallel
|
||||
argument-hint: "[plan file path or plan content]"
|
||||
---
|
||||
|
||||
Have @agent-dhh-rails-reviewer @agent-kieran-rails-reviewer @agent-code-simplicity-reviewer review this plan in parallel.
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: technical_review
|
||||
description: Have multiple specialized agents review the technical approach and architecture of a plan in parallel
|
||||
argument-hint: "[plan file path or plan content]"
|
||||
---
|
||||
|
||||
Have @agent-dhh-rails-reviewer @agent-kieran-rails-reviewer @agent-code-simplicity-reviewer review the technical approach in this plan in parallel.
|
||||
@@ -85,10 +85,19 @@ Use **AskUserQuestion tool** to present next steps:
|
||||
**Question:** "Brainstorm captured. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
|
||||
2. **Refine design further** - Continue exploring
|
||||
1. **Review and refine** - Improve the document through structured self-review
|
||||
2. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
|
||||
3. **Done for now** - Return later
|
||||
|
||||
**If user selects "Review and refine":**
|
||||
|
||||
Load the `document-review` skill and apply it to the brainstorm document.
|
||||
|
||||
When document-review returns "Review complete", present next steps:
|
||||
|
||||
1. **Move to planning** - Continue to `/workflows:plan` with this document
|
||||
2. **Done for now** - Brainstorming complete. To start planning later: `/workflows:plan [document-path]`
|
||||
|
||||
## Output Summary
|
||||
|
||||
When complete, display:
|
||||
|
||||
@@ -498,25 +498,25 @@ After writing the plan file, use the **AskUserQuestion tool** to present these o
|
||||
**Options:**
|
||||
1. **Open plan in editor** - Open the plan file for review
|
||||
2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
|
||||
3. **Run `/plan_review`** - Get feedback from reviewers (DHH, Kieran, Simplicity)
|
||||
4. **Start `/workflows:work`** - Begin implementing this plan locally
|
||||
5. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
|
||||
6. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
7. **Simplify** - Reduce detail level
|
||||
3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (DHH, Kieran, Simplicity)
|
||||
4. **Review and refine** - Improve the document through structured self-review
|
||||
5. **Start `/workflows:work`** - Begin implementing this plan locally
|
||||
6. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
|
||||
7. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
|
||||
Based on selection:
|
||||
- **Open plan in editor** → Run `open docs/plans/<plan_filename>.md` to open the file in the user's default editor
|
||||
- **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research
|
||||
- **`/plan_review`** → Call the /plan_review command with the plan file path
|
||||
- **`/technical_review`** → Call the /technical_review command with the plan file path
|
||||
- **Review and refine** → Load `document-review` skill.
|
||||
- **`/workflows:work`** → Call the /workflows:work command with the plan file path
|
||||
- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.md &` to start work in background for Claude Code web
|
||||
- **Create Issue** → See "Issue Creation" section below
|
||||
- **Simplify** → Ask "What should I simplify?" then regenerate simpler version
|
||||
- **Other** (automatically provided) → Accept free text for rework or specific changes
|
||||
|
||||
**Note:** If running `/workflows:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
|
||||
|
||||
Loop back to options after Simplify or Other changes until user selects `/workflows:work` or `/plan_review`.
|
||||
Loop back to options after Simplify or Other changes until user selects `/workflows:work` or `/technical_review`.
|
||||
|
||||
## Issue Creation
|
||||
|
||||
@@ -546,6 +546,6 @@ When user selects "Create Issue", detect their project tracker from CLAUDE.md:
|
||||
|
||||
5. **After creation:**
|
||||
- Display the issue URL
|
||||
- Ask if they want to proceed to `/workflows:work` or `/plan_review`
|
||||
- Ask if they want to proceed to `/workflows:work` or `/technical_review`
|
||||
|
||||
NEVER CODE! Just research and write the plan.
|
||||
|
||||
87
plugins/compound-engineering/skills/document-review/SKILL.md
Normal file
87
plugins/compound-engineering/skills/document-review/SKILL.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
name: document-review
|
||||
description: This skill should be used to refine brainstorm or plan documents before proceeding to the next workflow step. It applies when a brainstorm or plan document exists and the user wants to improve it.
|
||||
---
|
||||
|
||||
# Document Review
|
||||
|
||||
Improve brainstorm or plan documents through structured review.
|
||||
|
||||
## Step 1: Get the Document
|
||||
|
||||
**If a document path is provided:** Read it, then proceed to Step 2.
|
||||
|
||||
**If no document is specified:** Ask which document to review, or look for the most recent brainstorm/plan in `docs/brainstorms/` or `docs/plans/`.
|
||||
|
||||
## Step 2: Assess
|
||||
|
||||
Read through the document and ask:
|
||||
|
||||
- What is unclear?
|
||||
- What is unnecessary?
|
||||
- What decision is being avoided?
|
||||
- What assumptions are unstated?
|
||||
- Where could scope accidentally expand?
|
||||
|
||||
These questions surface issues. Don't fix yet—just note what you find.
|
||||
|
||||
## Step 3: Evaluate
|
||||
|
||||
Score the document against these criteria:
|
||||
|
||||
| Criterion | What to Check |
|
||||
|-----------|---------------|
|
||||
| **Clarity** | Problem statement is clear, no vague language ("probably," "consider," "try to") |
|
||||
| **Completeness** | Required sections present, constraints stated, open questions flagged |
|
||||
| **Specificity** | Concrete enough for next step (brainstorm → can plan, plan → can implement) |
|
||||
| **YAGNI** | No hypothetical features, simplest approach chosen |
|
||||
|
||||
If invoked within a workflow (after `/workflows:brainstorm` or `/workflows:plan`), also check:
|
||||
- **User intent fidelity** — Document reflects what was discussed, assumptions validated
|
||||
|
||||
## Step 4: Identify the Critical Improvement
|
||||
|
||||
Among everything found in Steps 2-3, does one issue stand out? If something would significantly improve the document's quality, this is the "must address" item. Highlight it prominently.
|
||||
|
||||
## Step 5: Make Changes
|
||||
|
||||
Present your findings, then:
|
||||
|
||||
1. **Auto-fix** minor issues (vague language, formatting) without asking
|
||||
2. **Ask approval** before substantive changes (restructuring, removing sections, changing meaning)
|
||||
3. **Update** the document inline—no separate files, no metadata sections
|
||||
|
||||
### Simplification Guidance
|
||||
|
||||
Simplification is purposeful removal of unnecessary complexity, not shortening for its own sake.
|
||||
|
||||
**Simplify when:**
|
||||
- Content serves hypothetical future needs, not current ones
|
||||
- Sections repeat information already covered elsewhere
|
||||
- Detail exceeds what's needed to take the next step
|
||||
- Abstractions or structure add overhead without clarity
|
||||
|
||||
**Don't simplify:**
|
||||
- Constraints or edge cases that affect implementation
|
||||
- Rationale that explains why alternatives were rejected
|
||||
- Open questions that need resolution
|
||||
|
||||
## Step 6: Offer Next Action
|
||||
|
||||
After changes are complete, ask:
|
||||
|
||||
1. **Refine again** - Another review pass
|
||||
2. **Review complete** - Document is ready
|
||||
|
||||
### Iteration Guidance
|
||||
|
||||
After 2 refinement passes, recommend completion—diminishing returns are likely. But if the user wants to continue, allow it.
|
||||
|
||||
Return control to the caller (workflow or user) after selection.
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
- Do not rewrite the entire document
|
||||
- Do not add new sections or requirements the user didn't discuss
|
||||
- Do not over-engineer or add complexity
|
||||
- Do not create separate review files or add metadata sections
|
||||
Reference in New Issue
Block a user