diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index b1a710d3..dd8d6e68 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -90,7 +90,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 | @@ -125,6 +125,8 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in | Skill | Description | |-------|-------------| +| `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 | diff --git a/plugins/compound-engineering/commands/deepen-plan.md b/plugins/compound-engineering/commands/deepen-plan.md index 2a2ed4f1..a7054764 100644 --- a/plugins/compound-engineering/commands/deepen-plan.md +++ b/plugins/compound-engineering/commands/deepen-plan.md @@ -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 diff --git a/plugins/compound-engineering/commands/plan_review.md b/plugins/compound-engineering/commands/plan_review.md deleted file mode 100644 index 70ef5ddc..00000000 --- a/plugins/compound-engineering/commands/plan_review.md +++ /dev/null @@ -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. diff --git a/plugins/compound-engineering/commands/technical_review.md b/plugins/compound-engineering/commands/technical_review.md new file mode 100644 index 00000000..8199542f --- /dev/null +++ b/plugins/compound-engineering/commands/technical_review.md @@ -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. diff --git a/plugins/compound-engineering/commands/workflows/brainstorm.md b/plugins/compound-engineering/commands/workflows/brainstorm.md index 3cb204d7..b9432db8 100644 --- a/plugins/compound-engineering/commands/workflows/brainstorm.md +++ b/plugins/compound-engineering/commands/workflows/brainstorm.md @@ -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: diff --git a/plugins/compound-engineering/commands/workflows/plan.md b/plugins/compound-engineering/commands/workflows/plan.md index 92e5aa39..a199ccaf 100644 --- a/plugins/compound-engineering/commands/workflows/plan.md +++ b/plugins/compound-engineering/commands/workflows/plan.md @@ -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/.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/.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. diff --git a/plugins/compound-engineering/skills/document-review/SKILL.md b/plugins/compound-engineering/skills/document-review/SKILL.md new file mode 100644 index 00000000..e9cb3b28 --- /dev/null +++ b/plugins/compound-engineering/skills/document-review/SKILL.md @@ -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