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>

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