Skip to content

Conversation

@tmchow
Copy link
Contributor

@tmchow tmchow commented Jan 23, 2026

Summary

Adds the document-review skill for improving brainstorm and plan documents through structured review, plus renames /plan_review/technical_review for clarity.

Changes

New document-review skill

A 6-step structured review process for improving document quality:

  1. Get the document - Read provided path or find recent brainstorm/plan
  2. Assess - Surface issues via reflective questions (What is unclear? What is unnecessary? What decision is being avoided?)
  3. Evaluate - Score against criteria (clarity, completeness, specificity, YAGNI)
  4. Identify critical improvement - Highlight the most impactful issue
  5. Make changes - Auto-fix minor issues, ask approval for substantive changes
  6. Offer next action - "Refine again" or "Review complete"

Key design decisions:

  • Generic and reusable (not coupled to specific workflows)
  • Soft iteration guidance (recommends 2 passes, doesn't enforce)
  • Returns control to calling workflow for next-step decisions

Renamed /plan_review/technical_review

The old name was confusing because "plan review" sounds like document review. The command actually spawns code-focused agents (DHH, Kieran, Simplicity) that review technical approach and architecture, not document quality.

  • document-review = document quality (clarity, YAGNI, structure)
  • /technical_review = technical approach (Rails conventions, code patterns, architecture)

Updated /workflows:brainstorm

Phase 4 handoff now offers "Review and refine" option. After document-review completes, brainstorm.md presents workflow-specific 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]

Why "Done for now"? After brainstorming and multiple refinement iterations, the context window can be full of back-and-forth that's no longer needed. "Done for now" lets users start a fresh session for planning with a clean context window, using only the finalized brainstorm document as input.

Updated /workflows:plan

Post-generation options now include:

  1. Review and refine - Load document-review skill for document quality pass

This complements /technical_review (option 3) which reviews the technical approach.

Updated README.md

  • Added document-review skill to skills table
  • Renamed /plan_review/technical_review in commands table

How it works

brainstorm/plan completes
    ↓
"Review and refine?" → loads document-review skill
    ↓
skill reviews document, makes changes with approval
    ↓
"Refine again" or "Review complete"
    ↓
calling workflow presents next steps

Test plan

  • Run /workflows:brainstorm and select "Review and refine" at handoff
  • Verify document-review skill loads and applies review questions
  • Verify changes require approval before substantive edits
  • After review completes, verify brainstorm.md presents next step options
  • Run /workflows:plan and select "Review and refine"
  • Run /technical_review and verify it still works with new name
  • Test standalone invocation: load document-review skill directly on a document

@tmchow tmchow force-pushed the feat/document-review-skill branch 7 times, most recently from 7d666d7 to 5fcccae Compare January 23, 2026 07:52
@tmchow tmchow marked this pull request as draft January 23, 2026 08:03
@tmchow tmchow force-pushed the feat/document-review-skill branch from 5fcccae to 29b29d8 Compare January 23, 2026 08:11
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
@tmchow tmchow force-pushed the feat/document-review-skill branch from 29b29d8 to a17ff11 Compare January 23, 2026 08:13
@tmchow tmchow marked this pull request as ready for review January 23, 2026 08:32
kprimdal added a commit to primux-dk/laravel-compound-engineering that referenced this pull request Jan 24, 2026
Adds the document-review skill for improving brainstorm and plan
documents through structured review, plus renames /plan_review →
/technical_review for clarity.

Changes:

### New document-review skill
A 6-step structured review process for improving document quality:
1. Get the document
2. Assess (surface issues via reflective questions)
3. Evaluate (score against criteria)
4. Identify critical improvement
5. Make changes (auto-fix minor, ask approval for substantive)
6. Offer next action

### Renamed /plan_review → /technical_review
The old name was confusing because "plan review" sounds like document
review. The command actually spawns code-focused agents that review
technical approach and architecture.

- document-review = document quality (clarity, YAGNI, structure)
- /technical_review = technical approach (Laravel conventions, patterns)

### Updated workflows
- /workflows:brainstorm now offers "Review and refine" option
- /workflows:plan includes "Review and refine" option
- /deepen-plan references updated to /technical_review

Note: Please manually delete commands/plan_review.md (blocked by hook)

Inspired by EveryInc#112

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant