Paw Plan Review

---
name: paw-plan-review
description: Plan review activity skill for PAW workflow. Reviews implementation plans for feasibility, completeness, and spec alignment before implementation proceeds.
---

# Plan Review

> **Execution Context**: This skill runs in a **subagent** session, delegated by the PAW orchestrator. Return structured feedback (pass/fail + issues) to the orchestrator—do not make orchestration decisions.

Review implementation plans for quality, feasibility, and alignment with specification before implementation proceeds.

> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.

## Capabilities

- Review ImplementationPlan.md for feasibility, completeness, and spec alignment
- Validate against quality criteria
- Identify specific phases or sections needing revision
- Return structured feedback with pass/fail status

## Desired End State

- Plan reviewed against all quality criteria
- Specific issues identified with actionable feedback
- Structured PASS/FAIL response returned to PAW agent

## Quality Criteria

### Spec Coverage

- [ ] All spec requirements mapped to plan phases
- [ ] User stories have corresponding implementation work
- [ ] Success criteria from spec reflected in phase success criteria
- [ ] No spec requirements orphaned (missing from plan)

### Phase Feasibility

- [ ] Each phase has clear, testable success criteria
- [ ] Phase boundaries are logical (not too large, not too small)
- [ ] Dependencies between phases are explicit
- [ ] Phases build incrementally and can be reviewed independently

### Completeness

- [ ] No placeholder content or TBDs
- [ ] All file paths and components specified
- [ ] Unit tests specified alongside code they test
- [ ] "What We're NOT Doing" section exists

### Research Integration

- [ ] Code research findings incorporated (file:line references)
- [ ] Documentation System section from CodeResearch.md considered
- [ ] Existing patterns referenced where applicable

### Strategic Focus

- [ ] Changes describe WHAT not HOW (interfaces, responsibilities)
- [ ] Code blocks limited to architectural concepts (<10 lines)
- [ ] No implementation algorithms or pseudo-code
- [ ] Significant decisions include trade-off analysis

### Documentation Planning

- [ ] Documentation phase included (standard for all non-trivial changes)
- [ ] Docs.md specified for technical reference (always required)
- [ ] Project docs updates included if user-facing or API changes exist
- [ ] If project docs omitted: reason provided

## Review Process

1. Read ImplementationPlan.md completely
2. Cross-reference with Spec.md for coverage
3. Check CodeResearch.md integration
4. Evaluate each quality criteria category
5. Compile specific issues with locations
6. Determine overall PASS/FAIL status

## Feedback Categories

| Category | Description |
|----------|-------------|
| **BLOCKING** | Must fix before implementation (missing requirements, infeasible phases) |
| **IMPROVE** | Should address but not blocking (clarity, organization) |
| **NOTE** | Observation for awareness (minor suggestions, alternatives) |

## Completion Response

Return structured feedback to PAW agent:

**PASS**: Plan meets quality criteria, ready for implementation
- Confirm spec coverage complete
- Note any non-blocking observations

**FAIL**: Plan needs revision before implementation
- List blocking issues with specific locations
- Categorize issues (BLOCKING, IMPROVE)
- Suggest what needs to change (not how to change it)

### Response Content

Include in completion response:
- Overall status: PASS or FAIL
- Spec coverage assessment: which requirements are covered, any gaps
- Phase feasibility assessment: any phases too large, unclear, or missing dependencies
- Completeness check: any TBDs, missing tests, incomplete sections
- Specific issues: categorized with plan section references
- Recommendation: proceed to implementation or revise plan

## Non-Responsibilities

- Do NOT make orchestration decisions (PAW agent handles next steps)
- Do NOT modify the plan directly (return feedback for planning skill to address)
- Do NOT implement changes (review only)
- Do NOT handle handoffs (return status to PAW agent)