Plan Review Skill

Evaluate research findings and decide whether to adjust upcoming stories in the PRD.

The Job

• Read the research report for the current story

• Evaluate if findings impact the current or future stories

• Decide on plan modifications (if any)

• Update prd.json with changes

• Document all changes in changeLog

• Ensure plan remains coherent and achievable

When to Modify the Plan

MODIFY stories when research reveals:

• A better technical approach than originally planned

• Missing prerequisite steps

• Stories that should be split (too large for one context)

• Stories that can be combined (too small, tightly coupled)

• Changed dependencies requiring reordering

• New edge cases requiring additional acceptance criteria

DO NOT modify when:

• The finding is interesting but doesn't affect implementation

• Changes would invalidate already-completed stories

• The modification is scope creep (outside original PRD goals)

Types of Plan Modifications

1. Modify Existing Story

Update acceptance criteria, description, or research topics.

{ "timestamp": "2026-01-29T12:00:00Z", "storyId": "US-002", "action": "modified", "reason": "Research found that existing badge component supports priority colors, simplifying implementation", "changes": { "acceptanceCriteria": { "removed": ["Create new PriorityBadge component"], "added": ["Reuse Badge component with priority color variant"] } } }

2. Add New Story

Insert a prerequisite or follow-up story.

{ "timestamp": "2026-01-29T12:00:00Z", "storyId": "US-001.5", "action": "added", "reason": "Research revealed need for database index on priority column for filter performance", "insertAfter": "US-001" }

3. Split Story

Break a story into smaller pieces.

{ "timestamp": "2026-01-29T12:00:00Z", "storyId": "US-003", "action": "split", "reason": "Story too large - separating dropdown component from save logic", "splitInto": ["US-003a", "US-003b"] }

4. Reorder Stories

Change priority/order based on new dependencies.

{ "timestamp": "2026-01-29T12:00:00Z", "storyId": "US-004", "action": "reordered", "reason": "URL state management needed before filter implementation", "newPriority": 2, "previousPriority": 4 }

5. Remove Story

Mark a story as unnecessary (cannot remove completed stories).

{ "timestamp": "2026-01-29T12:00:00Z", "storyId": "US-005", "action": "removed", "reason": "Research found this functionality already exists in the codebase" }

Plan Review Process

Step 1: Read Research Report

Load the research report from scripts/aha-loop/research/[story-id]-research.md

Focus on:

• Implementation recommendations

• Alternatives comparison (if recommendation differs from plan)

• Follow-up research needs

• Gotchas discovered

Step 2: Evaluate Impact

For each finding, ask:

Does this affect the current story?

• Update acceptance criteria if needed

• Add implementation notes

Does this affect future stories?

• Check if dependencies changed

• Check if new prerequisites needed

• Check if any stories can be simplified/removed

Does this reveal scope issues?

• Story too big? Split it.

• Story too small? Combine with related story.

• Missing stories? Add them.

Step 3: Draft Changes

Before modifying prd.json :

• List all proposed changes

• Verify no completed stories are affected

• Ensure changes maintain logical story order

• Check that all stories remain achievable in one context window

Step 4: Update prd.json

Backup first (automatic via aha-loop.sh, but verify).

Apply changes to prd.json :

// Example: Adding a story { "id": "US-001.5", "title": "Add database index for priority filtering", "description": "As a developer, I need an index on priority column for efficient filtering.", "acceptanceCriteria": [ "Create index on tasks.priority column", "Migration runs without errors", "Typecheck passes" ], "priority": 1.5, // Will be normalized later "passes": false, "researchTopics": [], "researchCompleted": true, // No research needed for simple index "learnings": "", "implementationNotes": "Discovered during US-001 research that filter queries will need this index", "notes": "" }

Add to changeLog:

{ "changeLog": [ // ... existing entries { "timestamp": "2026-01-29T12:00:00Z", "storyId": "US-001.5", "action": "added", "reason": "Research for US-001 revealed need for index to support efficient priority filtering (US-004)", "researchSource": "scripts/aha-loop/research/US-001-research.md" } ] }

Step 5: Normalize Priorities

After modifications, ensure priorities are sequential:

// Before: [1, 1.5, 2, 3, 4] // After: [1, 2, 3, 4, 5]

Safety Rules

NEVER:

• Delete or modify stories where passes: true

• Add scope beyond original PRD goals

• Create circular dependencies between stories

• Make changes without documenting in changeLog

ALWAYS:

• Document the reason for every change

• Reference the research source

• Maintain dependency order (schema → backend → UI)

• Keep stories small enough for one context window

Review Report Template

After plan review, append to progress.txt :

Plan Review - [Date/Time]

Research Analyzed

• [Story ID]: [Research report path]

Changes Made

[Action Type]: [Story ID]

• Reason: [Why this change was needed]
• Impact: [What this affects]

No Changes Made (If Applicable)

• Research findings do not require plan modifications
• Reason: [Why no changes needed]

Updated Story Order

1. US-001: [Title] ✓ (completed)
2. US-001.5: [Title] (new)
3. US-002: [Title] ...

Example: Complete Plan Review

Scenario: Research for US-001 (Add priority to database) revealed:

• An index is needed for filter performance

• The existing Badge component can be reused

• URL state management patterns already exist in codebase

Changes:

Add US-001.5 - Create index on priority column

• Reason: Filter queries (US-004) will be slow without index

Modify US-002 - Update acceptance criteria

• Remove: "Create PriorityBadge component"

• Add: "Reuse Badge component with 'priority' variant prop"

Modify US-004 - Add implementation note

• Note: "Use existing useUrlState hook from src/hooks/"

No reordering needed - dependencies unchanged.

Checklist

Before completing plan review:

• Research report fully analyzed

• All impacted stories identified

• No completed stories modified

• Changes documented in changeLog

• Priorities normalized

• Dependencies still valid

• All stories achievable in one context window

• Review summary added to progress.txt