Implementation Plan Review

Implementation Plan Review

This skill reviews generated implementation plans against established best practices to ensure quality, completeness, and development readiness.

Prerequisites

• Generated milestones.yaml file
• Associated milestone-m*.tasks.yaml files
• Optional: Source business-requirements.yaml and technical-requirements.yaml for alignment checks

Review Process

Phase 1: Structure Validation

Load and parse all plan files:

1. File Discovery

• Locate milestones.yaml
• Find all milestone-m*.tasks.yaml files
• Verify all referenced task files exist

2. Schema Validation

• Validate YAML syntax
• Check required fields present
• Verify data types and formats

3. Reference Integrity

• Validate milestone dependencies exist
• Validate task dependencies exist
• Check task file references match milestones

Phase 2: Best Practices Compliance

Review against embedded best practices. Note: Some checks vary by target audience:

• AI audience: Expect full TDD checklists, drift policy, explicit step-by-step instructions
• Human audience: Expect high-level objectives, constraints, and success criteria only
• Hybrid audience: Expect moderate detail with key guidance points

Adjust expectations accordingly when reviewing instruction detail level.

Target Audience Validation

• [ ] Metadata includes target_audience — milestones.yaml has meta.target_audience field
• [ ] Valid audience value — one of: "ai", "human", "hybrid"
• [ ] Instruction detail matches audience — review sample tasks to verify:
• AI: includes implementation steps, TDD checklist, explicit constraints, drift policy
• Human: includes objective, style anchors, key requirements, success criteria only
• Hybrid: includes objective, style anchors, implementation approach, validation guidance
• [ ] Consistency across tasks — all tasks follow the same detail level

Task Summaries

• [ ] task_summaries section present at top of each milestone-m*.tasks.yaml
• [ ] All tasks have summaries (every task ID in tasks array has a corresponding entry)
• [ ] Summaries are concise (20-300 characters, typically 1-2 sentences)
• [ ] Plain English (not technical jargon or implementation details)
• [ ] Active voice ("Creates X", not "X is created")
• [ ] Focus on what/why not how
• [ ] Scannable overview - reading summaries alone gives sense of milestone scope

Style Anchors

• [ ] 2-3 style anchors included per milestone task file
• [ ] Concrete file paths (not abstract descriptions)
• [ ] Specific line numbers provided
• [ ] Complete examples (code + tests + README where applicable)
• [ ] Current patterns reflecting best practices
• [ ] Clear descriptions explaining what pattern is demonstrated

Task Sizing (from task-sizing.md)

• [ ] Minimum 30 minutes per task (document rationale if smaller)
• [ ] Optimal 30-150 minutes for most tasks
• [ ] Maximum 150 minutes (2.5 hours) - split if larger
• [ ] Limited file scope (1-3 files preferred, >5 requires justification)
• [ ] Clear deliverables for each task
• [ ] Acceptance tests defined

TDD Requirements (AI audience only)

• [ ] TDD checklist included for code tasks — AI only
• [ ] Test-first approach specified — AI only
• [ ] Validation commands provided — AI/Hybrid: explicit, Human: general guidance
• [ ] Expected outputs documented — AI only
• [ ] Test modification forbidden when tests fail — AI only

For Human/Hybrid audiences, verify success criteria include testing requirements without prescriptive TDD checklists.

Affirmative Instructions

• [ ] Permitted actions explicit (e.g., "ONLY use: X, Y, Z") — AI/Hybrid only
• [ ] Constraints clear and actionable — All audiences

Drift Prevention (AI audience only)

• [ ] Drift policy stated in task instructions — AI only
• [ ] Stop criteria clear (unexpected dependencies, file scope violations) — AI only
• [ ] Revert instructions provided — AI only
• [ ] Incident documentation process specified — AI only
• [ ] Allowed deviations understood (formatting, whitespace) — AI only

Human/Hybrid audiences should still have clear constraints but not explicit drift policies.

Quality Gates

• [ ] Pre-commit hooks defined
• [ ] Validation commands specified per task
• [ ] Success criteria measurable
• [ ] Failure handling documented

Prompt Positioning

• [ ] Critical specs at beginning of task instructions
• [ ] Style anchors early in task definitions
• [ ] Hard rules reiterated at end
• [ ] Requirements not buried in middle

Phase 3: Drift Policy Compliance

Review against embedded drift policy:

Stop & Revert Criteria Coverage

Check that tasks include guidance for:

• [ ] New dependencies detection - How to identify unauthorized dependencies
• [ ] File scope violations - What to do if >3 unexpected files touched
• [ ] Linting/type errors - Handling unresolvable errors
• [ ] Test failures - Policy on modifying vs fixing implementation

Immediate Actions Documentation

• [ ] Stop instruction clear - "STOP immediately" language used
• [ ] Error message format - How to summarize deviation
• [ ] Revert process - When and how to revert
• [ ] Incident note location - Where to document (docs/drift-incidents/)

Recording Learnings

• [ ] Rule update process mentioned
• [ ] Where to update (.cursor/rules/, CLAUDE.md)

Allowed Deviations

• [ ] Minor formatting - Understood as acceptable
• [ ] Whitespace edits - Allowed without review
• [ ] Single-line refactors - Within scope and type-checked

Phase 4: Task Sizing Analysis

Review against embedded task sizing guidelines:

Duration Compliance

Generate report:

task_sizing_report:
  total_tasks: [count]
  by_duration:
    too_small:  # < 30m
      - task_id: [id]
        estimate_minutes: [n]
        rationale: [why small]
        recommendation: [merge or accept]
    optimal:    # 30-150m
      count: [n]
      percentage: [%]
    too_large:  # > 150m
      - task_id: [id]
        estimate_minutes: [n]
        recommendation: [split into X, Y, Z]

File Scope Analysis

• [ ] 1-3 files preferred
• [ ] >5 files justified or split
• [ ] Explicit file lists in each task
• [ ] Touch-only files clearly marked

Task Decomposition Quality

• [ ] Smallest useful deliverable defined
• [ ] Clear acceptance test per task
• [ ] Example files provided
• [ ] Commit after each task strategy

Large Task Detection

Identify tasks requiring decomposition:

decomposition_needed:
  - task_id: [id]
    current_estimate: [minutes]
    suggested_split:
      - name: [subtask 1]
        estimate: [minutes]
      - name: [subtask 2]
        estimate: [minutes]
      - name: [subtask 3]
        estimate: [minutes]

Phase 5: Completeness Check

Milestone Structure

• [ ] All milestones have unique IDs
• [ ] Names are clear and descriptive
• [ ] Descriptions explain deliverables
• [ ] Dependencies correctly ordered
• [ ] No circular dependencies
• [ ] Estimated durations realistic
• [ ] Task files referenced correctly
• [ ] Success criteria testable

Task Breakdown

• [ ] All tasks have unique IDs
• [ ] Task names descriptive
• [ ] Descriptions clear and actionable
• [ ] Estimates follow sizing rules
• [ ] Types specified (code/test/docs/config)
• [ ] Dependencies explicit and correct
• [ ] File lists complete and accurate
• [ ] Instructions detailed and clear

Task Quality

• [ ] Objectives clearly stated
• [ ] Implementation steps numbered
• [ ] Constraints explicit
• [ ] TDD checklists included (code tasks)
• [ ] Validation commands provided
• [ ] Expected outputs documented
• [ ] Drift policy stated

Phase 6: Alignment Check

Business Requirements (if provided)

• [ ] All functional requirements mapped to tasks
• [ ] Priority aligns with business priorities
• [ ] MVP scope clearly defined
• [ ] Success criteria can verify business goals

Generate coverage matrix:

business_requirement_coverage:
  FR-1: [task-ids]
  FR-2: [task-ids]
  FR-3: [gap]  # Not covered

Technical Requirements (if provided)

• [ ] Architecture decisions reflected
• [ ] Technology choices enforced
• [ ] Testing strategy implemented
• [ ] Security requirements addressed
• [ ] Performance requirements considered

Generate coverage matrix:

technical_requirement_coverage:
  architecture:
    - decision: [description]
      enforced_in: [task-ids]
  technology:
    - choice: [description]
      enforced_in: [task-ids]

Phase 7: Dependency Analysis

Critical Path

• [ ] Critical path identified
• [ ] Duration calculated
• [ ] Parallel opportunities noted
• [ ] Unnecessary dependencies removed
• [ ] Dependencies minimal but sufficient

Generate dependency graph:

dependency_analysis:
  critical_path:
    - [milestone-id]
    - [milestone-id]
  critical_path_duration: [time]
  
  parallel_opportunities:
    - can_parallelize: [[m1, m2], [m3, m4]]
      time_saved: [duration]
  
  dependency_issues:
    - task: [id]
      issue: [description]
      recommendation: [fix]

Circular Dependency Check

• [ ] No circular dependencies in milestones
• [ ] No circular dependencies in tasks
• [ ] Dependency graph is a DAG

Phase 8: Gap Identification

Common Gaps

• [ ] Infrastructure tasks present (setup, tooling)
• [ ] Test tasks included
• [ ] Documentation tasks included
• [ ] Error handling tasks included
• [ ] Configuration tasks included
• [ ] Deployment/release tasks included
• [ ] Assumptions documented
• [ ] Style anchors for new patterns
• [ ] Clear file boundaries
• [ ] Integration tasks between components

Generate gap report:

gaps:
  missing_task_types:
    - type: [infrastructure/tests/docs/etc]
      importance: [high/medium/low]
      recommendation: [description]
  
  missing_requirements_coverage:
    - requirement: [id]
      category: [functional/non-functional]
      impact: [high/medium/low]
  
  undocumented_assumptions:
    - task: [id]
      assumption: [description]
      recommendation: [document explicitly]

Wireframe Coverage (Soft Gate)

If any tasks reference .tsx/.jsx/.vue/.svelte files or mention UI components (forms, tables, navigation, modals, pages, layouts):

• [ ] Does ux/wireframe-spec.yaml exist?
• [ ] Does every page with UI tasks have a wireframe entry?
• [ ] Are all detected components represented in the wireframe spec?
• [ ] Are user flows documented for key interactions?

This is a WARN-level gate (not CRIT). It does NOT block progression.

If wireframes are missing or incomplete, add to the review output:

wireframe_coverage:
  ui_tasks_detected: [count]
  wireframe_spec_exists: [true/false]
  missing_pages:
    - page: [name]
      tasks: [task-ids]
  recommendation: "Consider running Step 6 (UX/Wireframe Planning) before development"

User sees:

"WARN-001: [n] UI tasks detected without wireframe coverage. Consider running Step 6 before development. Proceed anyway? (yes/no)"

Phase 9: Style Anchor Validation

• [ ] Anchors reference existing files (if repository available)
• [ ] Line numbers accurate (if verifiable)
• [ ] Patterns demonstrated correctly
• [ ] Descriptions helpful
• [ ] Sufficient anchors for each new pattern
• [ ] Test anchors included
• [ ] README anchors included where applicable

Phase 10: Quality Gate Validation

• [ ] Linter commands specified — AI: explicit, Human/Hybrid: general
• [ ] Type checker commands specified — AI: explicit, Human/Hybrid: general
• [ ] Test commands specified — AI: explicit, Human/Hybrid: general
• [ ] Commands are executable (where specified)
• [ ] Expected outputs defined — AI only
• [ ] Failure handling documented — AI only

For Human/Hybrid audiences, verify success criteria mention running tests/lint/typecheck without requiring explicit command text.

Review Output

Generate comprehensive review report as implementation-plan-review.yaml.

The output document includes: metadata (plan files, review date), overall_scores (structure, best practices, task sizing, completeness, alignment, development readiness — each 1-10), critical_issues, high_priority_issues, medium_priority_issues, best_practices_violations (by category), gaps, strong_areas, optimization_opportunities, specific_recommendations, and readiness_assessment.

See [references/output-spec.md](references/output-spec.md) for the complete document specification with all fields, issue IDs (CRIT-NNN/WARN-NNN/INFO-NNN), and scoring criteria.

See [references/example.yaml](references/example.yaml) for a full example.

Usage

Review an implementation plan:

/implementation-plan-review path/to/milestones.yaml

The skill will:

1. Load all milestone and task files 2. Validate structure and schema 3. Check compliance against all best practices 4. Analyze task sizing and dependencies 5. Identify gaps and issues 6. Generate comprehensive review report 7. Provide specific recommendations

Output Files

Generates:

• implementation-plan-review.yaml - Comprehensive review report
• task-sizing-analysis.yaml - Detailed task sizing breakdown
• requirement-coverage.yaml - Requirements to tasks mapping
• dependency-graph.yaml - Milestone and task dependencies

Best Practice References

This skill embeds and enforces best practices directly:

1. Implementation Plan Best Practices

Core Principle:

Models optimize locally; enforce global constraints with layered verification (prompt → IDE → commit → CI → runtime).

Key Practices:

• Style Anchors: Always include 2-3 exemplary files as templates with exact paths and line numbers. Prefer concrete repository examples (code + tests + README). Enforce anchors early to prevent architectural drift.
• Task Sizing: Split work into 30m–2.5h atomic tasks (30–150 minutes optimal). Limit scope to specific files. Commit after each small task. Revert immediately on drift. If a task is shorter than 30m, either increase estimate or split it with rationale.
• Affirmative Instructions: State permitted actions explicitly (e.g., "ONLY use: X, Y, Z"). Avoid negative framing.
• Tiered Rules: Global (user prefs), Project (persistent in CLAUDE.md or .cursor/rules/), Context-aware (per directory/file).
• TDD as Anchor: Require TDD checklist before implementation (tests → minimal code → more tests → refactor). When tests fail, return failing output with instruction: "Revise implementation to pass this test while keeping all previously passing tests. Do not modify the test. Do not add dependencies."
• Drift Handling: Stop and revert immediately on unexpected dependencies or unfamiliar patterns. Do not fix mid-stream. Document learnings and update persistent rules after each session.
• Prompt Positioning: Put critical specs, style anchors, and hard rules at the beginning and reiterate at the end of prompts (avoid burying requirements in the middle).
• External Data Validation: Never use type assertions on external data. Validate all external inputs with proper error handling and validation.

IDE/Linting:

• Enforce strict linting (go vet, golangci-lint, gofmt)
• Run tests with race detection
• Zero warnings policy

Quality Gates:

• Pre-commit: make lint and make test with zero warnings
• CI: Count violations and fail if thresholds exceeded

2. Drift Policy

Purpose: Define when to stop, revert, and document when the model's edits deviate from project rules.

Stop & Revert Criteria:

• Model introduces new dependencies not listed in allowed stack
• Edits touch files outside specified targets (>3 unexpected files)
• Linting or type errors introduced that cannot be resolved within task scope
• Tests fail and model proposes changing tests to pass

Immediate Actions: 1. Stop the model session and return clear error message summarizing deviation 2. Revert workspace to state before task started (use git where appropriate) 3. Create incident note in docs/drift-incidents/ with: what happened, files changed, new dependencies, remediation steps

Recording Learnings:

• After resolving, update .cursor/rules/ or CLAUDE.md with new rules to prevent recurrence

Allowed Deviations:

• Minor formatting changes (editor config) or whitespace-only edits
• Single-line refactors within targeted files if within scope and type-checked

Review & Approval:

• Any revert or incident note must be reviewed by human maintainer before re-running

3. Task Sizing Guidance

Purpose: Keep model-directed work in predictable, reviewable chunks to reduce drift and unexpected scope growth.

Guidelines:

• Target task duration: 30 minutes to 2.5 hours
• Prefer changes limited to 1-3 files where possible
• If a requested change touches >5 files or will take >2.5 hours, split into smaller tasks

Process: 1. Define smallest useful deliverable and clear acceptance test 2. Provide example files and exact paths to edit 3. After each completed task, run tests and commit with clear message

Breaking Down Large Tasks:

• Decompose into: (a) tests + scaffolding, (b) minimal implementation, (c) refactor & polish
• Create plan note listing sub-tasks and acceptance criteria

Examples:

• Small: fix a bug in src/utils/parse.ts — 30-60 mins
• Medium: add new API endpoint src/server/user.ts with tests — 1-2.5 hours
• Large: migrate auth system — split into design + incremental PRs

Decision Support

After review, provide recommendations:

If Critical Issues Found

"I've identified [n] critical issues that block development:

>

1. [Critical issue 1]

2. [Critical issue 2]

>

Recommendation: Fix these issues before starting development.

>

Would you like to:

1. Fix issues now (I'll regenerate affected tasks)

2. Review issues manually

3. Proceed with awareness (not recommended)"

If High Priority Issues Found

"I've identified [n] high-priority issues that should be addressed:

>

1. [Issue 1]

2. [Issue 2]

>

Recommendation: Address these before development or early in milestone 0.

>

Would you like to:

1. Address now (I'll update the plan)

2. Note for milestone 0

3. Proceed and handle as needed"

If Ready with Modifications

"The plan is mostly ready with [n] recommended improvements.

>

Strong areas:

- [What's well-planned]

>

Recommended improvements:

- [Improvement 1]

- [Improvement 2]

>

Timeline impact: [estimate]

>

Would you like to:

1. Apply improvements now

2. Note for implementation

3. Start development as-is"

If Ready for Development

"The implementation plan is ready for development!

>

Strengths:

- [What's excellent]

- [Best practices followed]

>

Minor optimization opportunities:

- [Opportunity 1]

- [Opportunity 2]

>

Estimated timeline: [duration]

Critical path: [duration]

>

You can begin development with confidence."

Integration

This skill integrates with:

• implementation-planner - Reviews plans generated by this skill
• business-requirements-interview - Validates alignment with business needs
• technical-requirements-interview - Validates technical specification coverage

Examples

See [references/example.yaml](references/example.yaml) for a complete sample review output.

Implementation Plan Review YAML Specification

Document Type: implementation-plan-review.yaml Version: 1.0.0 Generated By: implementation-plan-review skill Purpose: Quality gate document that validates generated implementation plans (milestones.yaml + milestone-m*.tasks.yaml) for development readiness. Ensures compliance with best practices, validates completeness, and provides actionable remediation guidance before development begins.

---

Document Structure

Root Level

metadata:
  review_date: string              # ISO 8601 timestamp (required)
  reviewer: string                 # Reviewer name or "automated" (required)
  plan_version: string             # Semantic version (required)
  reviewed_files: array<string>    # Files reviewed (required)

Validation Rules:

• review_date: ISO 8601 format (e.g., "2026-04-15T14:30:00Z")
• reviewer: 2-100 characters (human name, "automated", or "Claude Code")
• plan_version: Semantic version format (e.g., "1.0.0", "2.1.3")
• reviewed_files: 1-50 entries, each must be existing file path

Example:

metadata:
  review_date: "2026-04-15T14:30:00Z"
  reviewer: "automated"
  plan_version: "1.0.0"
  reviewed_files:
    - milestones.yaml
    - milestone-m0.tasks.yaml
    - milestone-m1.tasks.yaml
    - milestone-m2.tasks.yaml

Overall Assessment Section

overall_assessment:
  status: enum                     # Review outcome (required)
  readiness_score: number          # 0-100 (required)
  summary: string                  # Executive summary (required)
  critical_issues_count: number    # Critical issue count (required)
  warnings_count: number           # Warning count (required)

Status Enum:

• approved: Plan is development-ready, no critical issues
• needs_revision: Non-critical issues found, can proceed with caution
• rejected: Critical issues found, must fix before development

Readiness Score Calculation:

• 90-100: Excellent - approved
• 70-89: Good - needs_revision (minor fixes)
• 50-69: Fair - needs_revision (moderate fixes)
• 0-49: Poor - rejected (major rework required)

Validation Rules:

• status: Must be approved, needs_revision, or rejected
• readiness_score: Integer 0-100
• summary: 50-500 characters, clear executive summary
• critical_issues_count: Non-negative integer, matches critical issues array length
• warnings_count: Non-negative integer, matches warnings array length

Status Logic:

• If critical_issues_count > 0 → status must be rejected
• If readiness_score >= 90 and critical_issues_count == 0 → status should be approved
• If readiness_score < 90 and critical_issues_count == 0 → status should be needs_revision

Example:

overall_assessment:
  status: needs_revision
  readiness_score: 78
  summary: "Plan structure is solid with 12 well-defined tasks across 3 milestones. Task sizing compliance is 83% (10/12 tasks). Two tasks exceed 2.5h limit. Style anchor coverage is good. Missing TDD requirements in 3 tasks."
  critical_issues_count: 0
  warnings_count: 5

Validation Results Section

validation_results:
  milestones_validation:
    - check: string                # Check description (required)
      status: enum                 # pass | fail | warning (required)
      details: string              # Additional context (optional)

  tasks_validation:
    - milestone_id: string         # Milestone ID (required)
      checks:
        - check: string            # Check description (required)
          status: enum             # pass | fail | warning (required)
          affected_tasks: array<string> # Task IDs (optional)
          details: string          # Additional context (optional)

Check Categories for Milestones: 1. Schema Compliance

• All required fields present
• Field types correct
• Enum values valid

2. Field Validation

• Milestone IDs sequential (m0, m1, m2...)
• Names descriptive (10-150 chars)
• Descriptions complete (50-500 chars)
• Dependencies valid (reference existing milestones)

3. Success Criteria

• 3-8 criteria per milestone
• Criteria specific and testable
• Aligned with requirements

4. Cross-File Consistency

• Milestone IDs match across milestones.yaml and task files
• Names consistent across files

Check Categories for Tasks: 1. Schema Compliance

• All required fields present
• Task IDs sequential (m0-001, m0-002...)
• Field types correct

2. Task Sizing

• estimate_minutes within 30-150 range
• Estimates realistic for scope

3. Dependencies

• All referenced task IDs exist
• No circular dependencies
• Dependencies within same milestone

4. Files Specification

• At least one of: create, modify, touch_only
• Paths relative to project root
• No duplicate file paths

5. Instructions Quality

• 100-2000 characters
• Includes objective, steps, constraints
• References style anchors by code

Example:

validation_results:
  milestones_validation:
    - check: "All required root fields present"
      status: pass
    - check: "Milestone IDs sequential and properly formatted"
      status: pass
    - check: "All milestones have 3-8 success criteria"
      status: warning
      details: "Milestone m2 has only 2 success criteria (recommended: 3-8)"
    - check: "Milestone names descriptive and unique"
      status: pass

  tasks_validation:
    - milestone_id: m0
      checks:
        - check: "All required task fields present"
          status: pass
        - check: "Task IDs sequential (m0-001, m0-002...)"
          status: pass
        - check: "Task estimates within 30-150 minutes"
          status: warning
          affected_tasks: [m0-004]
          details: "Task m0-004 estimates 180 minutes (exceeds 150 limit)"
        - check: "No circular dependencies"
          status: pass
    - milestone_id: m1
      checks:
        - check: "All required task fields present"
          status: pass
        - check: "Task IDs sequential (m1-001, m1-002...)"
          status: pass
        - check: "All files have proper paths"
          status: pass

Best Practices Review Section

best_practices_review:
  task_sizing:
    compliant_count: number        # Tasks within 30-150 min (required)
    total_count: number            # Total tasks (required)
    compliance_percentage: number  # Percentage (required)
    violations:
      - task_id: string            # Task ID (required)
        estimated_minutes: number  # Actual estimate (required)
        issue: string              # Issue description (required)
        recommendation: string     # Fix suggestion (required)

  style_anchors:
    coverage_score: number         # 0-100 (required)
    tasks_with_anchors: number     # Count (required)
    tasks_without_anchors: number  # Count (required)
    missing_anchors:
      - task_id: string            # Task ID (required)
        task_name: string          # Task name (required)
        reason: string             # Why anchor needed (required)

  tdd_requirements:
    test_first_compliance: number  # Percentage (required)
    tdd_flag_set: boolean          # global_constraints.tdd_required (required)
    violations:
      - task_id: string            # Task ID (required)
        issue: string              # Issue description (required)
        recommendation: string     # Fix suggestion (required)

  drift_prevention:
    affirmative_instructions: number # Percentage (required)
    ambiguous_tasks:
      - task_id: string            # Task ID (required)
        issue: string              # Ambiguity description (required)
        recommendation: string     # Fix suggestion (required)

Task Sizing Compliance:

• Target: 100% of tasks between 30-150 minutes
• Good: ≥90% compliance
• Acceptable: ≥80% compliance
• Poor: <80% compliance

Style Anchor Coverage:

• Excellent: ≥90% of code tasks have anchor references
• Good: 70-89% coverage
• Fair: 50-69% coverage
• Poor: <50% coverage

TDD Compliance:

• If tdd_required: true, check for test-first instructions
• Look for: "Write test first", "TDD", "test-driven" in instructions
• Target: 100% if tdd_required is true

Affirmative Instructions:

• Instructions should say what TO DO, not just what NOT to do
• Target: ≥80% affirmative (vs. negative/restrictive)
• Look for: Action verbs, "use X", "follow Y" vs. "don't use", "avoid"

Example:

best_practices_review:
  task_sizing:
    compliant_count: 10
    total_count: 12
    compliance_percentage: 83
    violations:
      - task_id: m0-004
        estimated_minutes: 180
        issue: "Exceeds maximum 150-minute limit"
        recommendation: "Split into two tasks: 1) Core implementation (90m), 2) Edge cases and validation (90m)"
      - task_id: m2-007
        estimated_minutes: 25
        issue: "Below minimum 30-minute threshold"
        recommendation: "Combine with m2-008 (similar scope) into single 60-minute task"

  style_anchors:
    coverage_score: 85
    tasks_with_anchors: 9
    tasks_without_anchors: 2
    missing_anchors:
      - task_id: m1-003
        task_name: "Implement UserService"
        reason: "Service implementation should reference SA-001 (Effect.Service pattern)"

  tdd_requirements:
    test_first_compliance: 75
    tdd_flag_set: true
    violations:
      - task_id: m0-002
        issue: "tdd_required is true but task instructions don't specify test-first approach"
        recommendation: "Add 'Write failing test first' as step 1 in instructions"
      - task_id: m1-005
        issue: "No testing requirements in instructions despite tdd_required flag"
        recommendation: "Add Testing Requirements section with test-first workflow"

  drift_prevention:
    affirmative_instructions: 82
    ambiguous_tasks:
      - task_id: m2-001
        issue: "Instructions say 'implement the feature' without specific steps"
        recommendation: "Break into concrete steps: 1) Create schema, 2) Implement repository, 3) Add service layer"

Requirements Alignment Section

requirements_alignment:
  business_requirements_coverage:
    - requirement_id: string       # BR ID (required)
      requirement_name: string     # Name (required)
      covered_by_milestones: array<string> # Milestone IDs (required)
      coverage_status: enum        # complete | partial | missing (required)
      gap_description: string      # If partial/missing (optional)

  technical_requirements_coverage:
    - requirement_id: string       # TR section (required)
      requirement_name: string     # Name (required)
      covered_by_tasks: array<string> # Task IDs (required)
      coverage_status: enum        # complete | partial | missing (required)
      gap_description: string      # If partial/missing (optional)

Coverage Status:

• complete: Requirement fully addressed by plan
• partial: Requirement partially addressed, gaps exist
• missing: Requirement not addressed at all

Validation Rules:

• requirement_id: Must reference actual requirement from business-requirements.yaml or technical-requirements.yaml
• coverage_status: If missing, covered_by_milestones or covered_by_tasks should be empty
• gap_description: Required if status is partial or missing

Example:

requirements_alignment:
  business_requirements_coverage:
    - requirement_id: BR-001
      requirement_name: "User Authentication"
      covered_by_milestones: [m0, m1]
      coverage_status: complete
    - requirement_id: BR-002
      requirement_name: "Real-time Notifications"
      covered_by_milestones: [m2]
      coverage_status: partial
      gap_description: "WebSocket implementation covered but push notification integration missing"
    - requirement_id: BR-003
      requirement_name: "Advanced Reporting"
      covered_by_milestones: []
      coverage_status: missing
      gap_description: "No milestones address reporting features - out of scope for v1.0?"

  technical_requirements_coverage:
    - requirement_id: TR-Architecture
      requirement_name: "Effect-ts Service Layer"
      covered_by_tasks: [m0-001, m0-002, m1-003, m1-005]
      coverage_status: complete
    - requirement_id: TR-Testing
      requirement_name: "80% Test Coverage"
      covered_by_tasks: [m0-003, m1-006, m2-008]
      coverage_status: partial
      gap_description: "Test tasks defined but no integration tests for API layer"

Issues Section

issues:
  critical:
    - id: string                   # Issue ID (required, format: CRIT-NNN)
      category: string             # Category (required)
      description: string          # Issue description (required)
      location: string             # File:line or milestone/task (required)
      impact: string               # Business/technical impact (required)
      remediation: string          # How to fix (required)

  warnings:
    - id: string                   # Issue ID (required, format: WARN-NNN)
      category: string             # Category (required)
      description: string          # Issue description (required)
      location: string             # File:line or milestone/task (required)
      recommendation: string       # How to improve (required)

  info:
    - id: string                   # Issue ID (required, format: INFO-NNN)
      category: string             # Category (required)
      description: string          # Observation (required)
      suggestion: string           # Optional improvement (optional)

Severity Levels:

1. Critical (MUST FIX before development)

• Schema violations
• Circular dependencies
• Invalid references (task IDs, style anchors, files)
• Missing required fields
• Broken plan structure

2. Warning (SHOULD FIX, can proceed with caution)

• Task sizing violations (too large/small)
• Missing style anchor references
• Weak instructions
• Missing TDD requirements
• Poor test coverage planning

3. Info (NICE TO HAVE, optional improvements)

• Task naming suggestions
• Dependency optimization opportunities
• Additional quality gates
• Documentation improvements

Issue Categories:

• schema: YAML structure and field validation
• task_sizing: Estimate violations
• dependencies: Task dependency issues
• instructions: Instruction quality problems
• style_anchors: Missing or incorrect anchor references
• tdd: Test-driven development requirement issues
• requirements_alignment: Coverage gaps
• quality_gates: Quality gate configuration issues
• best_practices: General best practice violations

Example:

issues:
  critical:
    - id: CRIT-001
      category: dependencies
      description: "Circular dependency detected"
      location: "milestone-m1.tasks.yaml"
      impact: "Tasks m1-003 and m1-005 depend on each other, making execution impossible"
      remediation: "Remove m1-005 from m1-003 dependencies. Task m1-003 should complete before m1-005 starts."

  warnings:
    - id: WARN-001
      category: task_sizing
      description: "Task exceeds maximum duration"
      location: "milestone-m0.tasks.yaml: m0-004"
      recommendation: "Split m0-004 (180 minutes) into two tasks: core implementation (90m) and validation (90m)"
    - id: WARN-002
      category: style_anchors
      description: "Service implementation task missing style anchor reference"
      location: "milestone-m1.tasks.yaml: m1-003"
      recommendation: "Add SA-001 reference for Effect.Service pattern"
    - id: WARN-003
      category: tdd
      description: "TDD flag enabled but instructions don't specify test-first approach"
      location: "milestone-m0.tasks.yaml: m0-002"
      recommendation: "Add 'Write failing test first' as step 1 in task instructions"

  info:
    - id: INFO-001
      category: best_practices
      description: "Task naming could be more specific"
      suggestion: "m2-001: 'Setup WebSocket' → 'Configure Socket.io server with Redis adapter'"
    - id: INFO-002
      category: quality_gates
      description: "No pre-push quality gate defined"
      suggestion: "Consider adding pre-push stage with full test suite and build check"

Recommendations Section

recommendations:
  - priority: enum                 # high | medium | low (required)
    category: string               # Category (required)
    recommendation: string         # Action to take (required)
    affected_items: array<string>  # Task/milestone IDs (optional)
    effort: string                 # Effort estimate (optional)

Priority Levels:

• high: Critical for plan quality, fix before development
• medium: Important for success, fix within first sprint
• low: Nice to have, consider for future iterations

Example:

recommendations:
  - priority: high
    category: task_sizing
    recommendation: "Split oversized tasks to stay within 30-150 minute guideline"
    affected_items: [m0-004, m2-007]
    effort: "30 minutes to redesign task breakdown"

  - priority: high
    category: tdd
    recommendation: "Add explicit test-first instructions to all code tasks (tdd_required is true)"
    affected_items: [m0-002, m1-005, m2-003]
    effort: "15 minutes to update task instructions"

  - priority: medium
    category: style_anchors
    recommendation: "Add style anchor references to service implementation tasks"
    affected_items: [m1-003, m2-005]
    effort: "10 minutes to add SA-001 references and update instructions"

  - priority: medium
    category: requirements_alignment
    recommendation: "Clarify scope: BR-003 (Advanced Reporting) not covered by any milestone"
    affected_items: []
    effort: "Discussion with stakeholders needed"

  - priority: low
    category: quality_gates
    recommendation: "Add pre-push quality gate with integration tests"
    affected_items: []
    effort: "20 minutes to add gate configuration"

Approval Section

approval:
  ready_for_development: boolean   # Approval status (required)
  conditions: array<string>        # Pre-conditions (conditional)
  approved_by: string              # Approver name (optional)
  approved_date: string            # ISO 8601 timestamp (optional)
  next_steps: array<string>        # Action items (optional)

Validation Rules:

• ready_for_development: Must be true if status is approved, false if rejected
• conditions: Required if status is needs_revision, describes what must be fixed
• approved_by: Required if ready_for_development: true
• approved_date: ISO 8601 format, required if approved

Example (Approved):

approval:
  ready_for_development: true
  conditions: []
  approved_by: "Claude Code"
  approved_date: "2026-04-15T15:00:00Z"
  next_steps:
    - "Review style anchors (docs/style-anchors/) before starting m0"
    - "Setup development environment per m0-001"
    - "Begin implementation with m0-002"

Example (Needs Revision):

approval:
  ready_for_development: false
  conditions:
    - "Fix task sizing violations (WARN-001, WARN-002)"
    - "Add test-first instructions to TDD tasks (WARN-003, WARN-004, WARN-005)"
    - "Add style anchor references to service tasks (WARN-006, WARN-007)"
    - "Clarify scope for BR-003 (missing from plan)"
  next_steps:
    - "Update milestone-m0.tasks.yaml and milestone-m2.tasks.yaml"
    - "Re-run implementation-plan-review skill"
    - "Obtain approval before starting development"

Example (Rejected):

approval:
  ready_for_development: false
  conditions:
    - "CRITICAL: Fix circular dependencies in m1 (CRIT-001)"
    - "CRITICAL: Fix invalid task ID references in m2 (CRIT-002)"
    - "CRITICAL: Add missing required fields in milestones.yaml (CRIT-003)"
  next_steps:
    - "Fix all critical issues"
    - "Re-generate implementation plan using implementation-planner skill"
    - "Re-run implementation-plan-review skill"

---

Field Type Reference

---

Validation Summary

Required Root Level

• ✓ metadata (with 4 sub-fields)
• ✓ overall_assessment (with 5 sub-fields)
• ✓ validation_results (milestones and tasks)
• ✓ best_practices_review (4 categories)
• ✓ requirements_alignment (business and technical)
• ✓ issues (critical, warnings, info arrays)
• ✓ recommendations (prioritized list)
• ✓ approval (with ready_for_development flag)

Critical Validation Checks

1. Schema Compliance

• All reviewed files exist
• YAML structure valid
• Required fields present
• Field types correct

2. Task Sizing

• 80%+ tasks within 30-150 minute range
• Oversized tasks identified for splitting
• Undersized tasks flagged for combination

3. Dependencies

• All task ID references valid
• No circular dependencies
• Dependencies within same milestone

4. Style Anchors

• Referenced codes exist in style-anchors/index.yaml
• Code tasks have anchor references
• Instructions explain anchor usage

5. TDD Compliance

• If tdd_required: true, check for test-first instructions
• Test tasks exist for code tasks
• Testing criteria defined

6. Requirements Alignment

• Business requirements mapped to milestones
• Technical requirements mapped to tasks
• Coverage gaps identified

Score Calculation

Readiness Score Factors:

• Schema compliance: 15%
• Task sizing compliance: 20%
• Style anchor coverage: 15%
• TDD compliance: 15%
• Instructions quality: 15%
• Requirements alignment: 10%
• Dependency validity: 10%

Formula:

readiness_score = (
  schema_compliance_pct * 0.15 +
  task_sizing_compliance_pct * 0.20 +
  style_anchor_coverage_pct * 0.15 +
  tdd_compliance_pct * 0.15 +
  instructions_quality_pct * 0.15 +
  requirements_coverage_pct * 0.10 +
  dependency_validity_pct * 0.10
)

---

Integration with Other Documents

Input Documents

• milestones.yaml → Milestone structure and success criteria
• milestone-m*.tasks.yaml → Task details, estimates, instructions
• business-requirements.yaml → Requirements coverage validation
• technical-requirements.yaml → Technical alignment validation
• style-anchors/index.yaml → Valid anchor codes for validation
• style-anchors/SA-*.md → Pattern documentation (reference only)

Output Documents

• Blocks development until approved or issues fixed
• Informs definition-of-done.yaml acceptance criteria
• Feeds into timeline.yaml adjustments if tasks resized

Related Documents

• delivery-timeline.yaml → May need adjustment if plan changes
• qa-test-plan.yaml → Task-test mapping validation

Workflow Position

business-requirements → technical-requirements → style-anchors
                                                       ↓
                            milestones.yaml ← implementation-planner
                                    ↓
                            milestone-m*.tasks.yaml (per milestone)
                                    ↓
                            implementation-plan-review.yaml ← QUALITY GATE
                                    ↓
                            [approved] → Development execution
                            [needs_revision] → Fix issues → Re-review
                            [rejected] → Regenerate plan → Re-review

---

Automated Validation vs Manual Review

Automated Checks (always run)

• Schema validation
• Field type checking
• Task ID sequencing
• Dependency graph analysis (circular check)
• Task sizing compliance
• Style anchor code existence
• File path validation
• Requirement ID references

Manual Review (human or AI)

• Instructions quality and clarity
• Requirement coverage completeness
• Architectural alignment
• Estimation reasonableness
• Success criteria effectiveness
• Overall plan feasibility

Hybrid Approach

Most effective: Automated validation + AI review + human sign-off for critical projects

---

CLI Tool Support

Validation Command

sherpy review-plan

Behavior:

• Auto-discovers milestones.yaml and milestone-m*.tasks.yaml in docs/
• Runs all automated validation checks
• Performs best practices review
• Generates implementation-plan-review.yaml in docs/
• Outputs summary to console
• Exits with code 0 if approved, 1 if needs_revision, 2 if rejected

Output:

Implementation Plan Review
==========================

Overall Status: NEEDS REVISION
Readiness Score: 78/100

Critical Issues: 0
Warnings: 5
Info: 2

⚠ WARN-001: Task m0-004 exceeds 150-minute limit (180 minutes)
⚠ WARN-002: Task m2-007 below 30-minute threshold (25 minutes)
⚠ WARN-003: m0-002 missing test-first instructions (tdd_required is true)
⚠ WARN-004: m1-003 service task missing SA-001 style anchor reference
⚠ WARN-005: m2-005 service task missing SA-001 style anchor reference

ℹ INFO-001: Consider more specific task name for m2-001
ℹ INFO-002: Consider adding pre-push quality gate

Recommendations:
  [HIGH] Split oversized tasks (m0-004, m2-007)
  [HIGH] Add test-first instructions (m0-002, m1-005, m2-003)
  [MEDIUM] Add style anchor references (m1-003, m2-005)

Review saved to: docs/implementation-plan-review.yaml

Next Steps:
  1. Fix warnings in milestone task files
  2. Re-run 'sherpy review-plan'
  3. Obtain approval before starting development

Score Report

sherpy review-plan --score

Output:

Readiness Score Breakdown
=========================

Schema Compliance:        100% (15 points)
Task Sizing Compliance:    83% (16.6 points)
Style Anchor Coverage:     85% (12.75 points)
TDD Compliance:            75% (11.25 points)
Instructions Quality:      88% (13.2 points)
Requirements Coverage:     90% (9 points)
Dependency Validity:      100% (10 points)

Total Readiness Score: 78/100
Status: NEEDS REVISION

---

Best Practices

When to Run Review

DO:

• After initial plan generation (implementation-planner)
• Before starting development
• After significant plan changes
• Before milestone handoff to development team

DON'T:

• Run multiple times without making changes
• Skip review for "small" projects
• Ignore warnings if they affect core quality

Interpreting Results

Approved (90-100 score, 0 critical issues):

• ✅ Ready for development
• Address info suggestions if time permits
• Proceed with confidence

Needs Revision (70-89 score, 0 critical issues):

• ⚠️ Can proceed with caution
• Fix high-priority warnings within first sprint
• Medium/low priorities can be addressed incrementally

Rejected (< 70 score or any critical issues):

• ❌ Must fix before development
• Re-generate plan if structural problems
• Re-run review after fixes

Fixing Common Issues

Oversized Tasks:

# Before (180 minutes)
- id: m0-004
  name: "Implement complete auth system"
  estimate_minutes: 180

# After (split into 2 tasks)
- id: m0-004
  name: "Implement auth service layer"
  estimate_minutes: 90
- id: m0-005
  name: "Add auth validation and error handling"
  estimate_minutes: 90
  dependencies: [m0-004]

Missing Style Anchors:

# Before
- id: m1-003
  name: "Implement UserService"
  instructions: |
    Create UserService with CRUD operations.

# After
- id: m1-003
  name: "Implement UserService"
  style_anchor_refs: [SA-001]
  instructions: |
    **Objective:** Create UserService following Effect.Service pattern.

    **Implementation Steps:**
    1. Review **SA-001** for service structure
    2. Create src/services/user-service.ts
    3. Follow SA-001 pattern for all methods

Missing TDD Instructions:

# Before (tdd_required: true)
instructions: |
  Create AccountService with CRUD operations.
  Implement findById, create, update methods.

# After
instructions: |
  **Objective:** Create AccountService with CRUD operations.

  **Implementation Steps:**
  1. Write failing test for findById (test-first)
  2. Implement findById to pass test
  3. Write failing test for create (test-first)
  4. Implement create to pass test
  5. Repeat for update method

---

Common Pitfalls

1. Skipping Review

Problem: Starting development without validating plan quality Impact: Discover structural issues mid-development, costly rework Solution: Always run review before development starts

2. Ignoring Warnings

Problem: "It's just a warning, we can proceed" Impact: Quality drift, inconsistent code, missed best practices Solution: Treat high/medium priority warnings seriously

3. Incomplete Fixes

Problem: Fixing some issues but not re-running review Impact: May introduce new issues or miss related problems Solution: Always re-run review after making changes

4. Over-Engineering Fixes

Problem: Adding unnecessary complexity to achieve 100% score Impact: Over-planned, rigid tasks that don't account for reality Solution: 90+ score is excellent; don't sacrifice pragmatism

5. Misunderstanding Severity

Problem: Treating critical issues as warnings Impact: Proceeding with broken plan structure Solution: Critical = must fix, Warning = should fix, Info = nice to have

---

Review Workflow Example

Initial Review

$ sherpy review-plan

Status: REJECTED
Score: 45/100
Critical: 2, Warnings: 8, Info: 3

❌ CRIT-001: Circular dependency (m1-003 ↔ m1-005)
❌ CRIT-002: Invalid task ID reference (m2-007 depends on m1-099)

After Fixing Critical Issues

$ sherpy review-plan

Status: NEEDS REVISION
Score: 72/100
Critical: 0, Warnings: 5, Info: 2

⚠ WARN-001: Task m0-004 exceeds 150-minute limit
⚠ WARN-002: Missing style anchor refs in 2 tasks

After Fixing Warnings

$ sherpy review-plan

Status: APPROVED
Score: 92/100
Critical: 0, Warnings: 0, Info: 2

✅ Plan approved for development
ℹ INFO-001: Consider more descriptive task names

---

Schema Version History

• 1.0.0 (2026-04-16): Initial specification
• Complete validation framework for milestones and tasks
• Best practices checks (task sizing, style anchors, TDD, drift prevention)
• Requirements alignment tracking
• Severity-based issue categorization
• Automated + manual review support
• Approval workflow with conditions

---

Examples

See example.yaml for a complete, realistic implementation plan review document showing needs_revision status with multiple warning categories.