Plan Review Skill

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

The Job

1. Read the research report for the current story
2. Evaluate if findings impact the current or future stories
3. Decide on plan modifications (if any)
4. Update prd.json with changes
5. Document all changes in changeLog
6. 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:

1. Does this affect the current story?

   • Update acceptance criteria if needed
   • Add implementation notes

2. Does this affect future stories?

   • Check if dependencies changed
   • Check if new prerequisites needed
   • Check if any stories can be simplified/removed

3. 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:

1. List all proposed changes
2. Verify no completed stories are affected
3. Ensure changes maintain logical story order
4. 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:

1. An index is needed for filter performance
2. The existing Badge component can be reused
3. URL state management patterns already exist in codebase

Changes:

1. Add US-001.5 – Create index on priority column

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

2. Modify US-002 – Update acceptance criteria

   • Remove: “Create PriorityBadge component”
   • Add: “Reuse Badge component with ‘priority’ variant prop”

3. 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