Scrum4Me/docs/implementation-complete/IDEA_REVIEW_PLAN-implementation-summary.md

IDEA_REVIEW_PLAN Implementation Summary

Date: May 14, 2026
Phase: Completed (Phases 1-5) | Ready for Testing (Phase 6)
Status: ✅ All core implementation complete

---

Overview

The IDEA_REVIEW_PLAN job kind has been fully implemented as a multi-model iterative plan review orchestrator. This feature enables automated review of implementation plans (YAML + markdown documents) with convergence detection and approval gates.

---

Implementation Checklist

Phase 1: Database & Config ✅

• Added plan_review_log (Json) and reviewed_at (DateTime) fields to Idea model
• Added REVIEWING_PLAN, PLAN_REVIEW_FAILED, PLAN_REVIEWED to IdeaStatus enum
• Added IDEA_REVIEW_PLAN to ClaudeJobKind enum
• Added PLAN_REVIEW_RESULT to IdeaLogType enum
• Created migration 20260514000000_add_review_plan_support
• Synchronized both Prisma schemas (main repo + scrum4me-mcp)
• Configured job-config.ts with:
  • Model: claude-opus-4-7
  • Thinking budget: 6000 tokens
  • Allowed tools: Read, Write, Grep, Glob, MCP tools

Phase 2: MCP Tool Implementation ✅

• Created update_idea_plan_reviewed MCP tool
• Implemented transaction-safe database updates
• Added error handling and access control
• Registered tool in MCP server index
• Type-safe Zod input validation

Phase 3: Server Actions & UI Components ✅

• Created startReviewPlanJobAction() server action
• Updated cancelIdeaJobAction() for IDEA_REVIEW_PLAN
• Updated status transition rules in lib/idea-status.ts
• Added status colors and labels for new statuses
• Updated job-card and jobs-column to display IDEA_REVIEW_PLAN
• Updated idea-timeline to display PLAN_REVIEW_RESULT log entries

Phase 4: Grill Prompt Implementation ✅

• Created lib/idea-prompts/review-plan-job.md prompt
• Copied prompt to MCP server at src/prompts/idea/review-plan.md
• Updated kind-prompts.ts to register the new prompt
• Updated getIdeaPromptText() to include IDEA_REVIEW_PLAN
• Updated wait-for-job.ts to handle IDEA_REVIEW_PLAN
• Updated branch suggestion logic for review jobs
• Created comprehensive documentation in docs/runbooks/review-plan-job.md
• Created test suite for review-log schema validation (__tests__/review-plan-job.test.ts)
• All tests passing (13/13 review-plan-job tests, 862 total tests)

Phase 5: ReviewLogViewer UI Component ✅

• Created components/ideas/review-log-viewer.tsx component
• Integrated component into idea page
• Display review-log in plan tab with convergence metrics
• Show round-by-round issues and scores
• Approval status display with proper styling
• Updated idea page to load and pass plan_review_log
• TypeScript compilation successful

Phase 6: Integration & Rollout 🔄 (In Progress)

• ✅ Wire wait-for-job discriminator (IDEA_REVIEW_PLAN already in condition at line 511)
• 📋 End-to-end testing with live job execution
• 📋 Verify IdeaLog entries and review-log persistence
• 📋 Feature flag management (if applicable)
• 📋 Rollout to staging (24h test)
• 📋 Gradual rollout: 10% → 50% → 100% (if using feature flags)

---

Files Modified/Created

Database & Schema

• prisma/schema.prisma - Added fields and enums
• prisma/migrations/20260514000000_add_review_plan_support/migration.sql - DDL

Configuration & Jobs

• lib/job-config.ts - IDEA_REVIEW_PLAN config
• scrum4me-mcp/src/lib/job-config.ts - Mirrored config

Server Actions

• actions/ideas.ts - startReviewPlanJobAction()

Prompts

• lib/idea-prompts/review-plan-job.md - Main prompt
• scrum4me-mcp/src/prompts/idea/review-plan.md - MCP server copy
• scrum4me-mcp/src/lib/kind-prompts.ts - Prompt registration

MCP Tools & Integration

• scrum4me-mcp/src/tools/update-idea-plan-reviewed.ts - MCP tool (NEW)
• scrum4me-mcp/src/tools/wait-for-job.ts - Updated discriminator
• scrum4me-mcp/src/lib/kind-prompts.ts - Prompt loader

UI Components

• components/ideas/review-log-viewer.tsx - Review-log display (NEW)
• components/ideas/idea-detail-layout.tsx - Integrated viewer
• components/ideas/idea-timeline.tsx - Added PLAN_REVIEW_RESULT icon
• components/ideas/idea-list.tsx - Added new statuses to filters
• components/ideas/idea-detail-layout.tsx - API_TO_DB mappings
• components/jobs/job-card.tsx - Added REVIEW kind label
• components/jobs/jobs-column.tsx - Added REVIEW filter option
• app/(app)/ideas/[id]/page.tsx - Load and pass plan_review_log

Status & Color Definitions

• lib/idea-status.ts - Status transitions & editability rules
• lib/idea-status-colors.ts - Color mappings for new statuses

Documentation & Tests

• docs/runbooks/review-plan-job.md - Implementation guide
• __tests__/review-plan-job.test.ts - Test suite (NEW)

---

Data Flow

User clicks "Review Plan" on PLAN_READY idea
  ↓
startReviewPlanJobAction() queues IDEA_REVIEW_PLAN job
  ↓
Server: PLAN_READY → REVIEWING_PLAN (atomic with job creation)
  ↓
Worker claims job via wait_for_job
  ↓
Prompt orchestrates review:
  • Ronde 1: Structure check
  • Ronde 2: Logic & patterns
  • Ronde 3: Risk assessment
  ↓
Convergence detection triggers
  ↓
User approves via ask_user_question
  ↓
update_idea_plan_reviewed(approval_status='approved')
  ↓
Atomic transaction:
  • Save plan_review_log
  • Save reviewed_at timestamp
  • Transition REVIEWING_PLAN → PLAN_REVIEWED
  • Create IdeaLog entry (PLAN_REVIEW_RESULT)
  ↓
UI updates: ReviewLogViewer shows results in plan tab

---

Key Features

1. Multi-Model Review: Haiku (structure) → Sonnet (logic) → Opus (risk)
2. Convergence Detection: Auto-stop when plan stabilizes (< 5% changes 2 rounds)
3. Approval Gate: User must approve before plan transitions to PLAN_REVIEWED
4. Rich Logging: Detailed review-log JSON with issues, scores, diffs per round
5. Status Transitions: Proper state machine with allowed transitions
6. IdeaLog Audit: PLAN_REVIEW_RESULT entries track all reviews
7. UI Integration: ReviewLogViewer shows convergence metrics, issues, approval status

---

Review-Log Schema

{
  plan_file: string;
  created_at: ISO8601;
  rounds: Array<{
    round: number;
    model: string;
    role: string;
    focus: string;
    plan_before: string;
    plan_after: string;
    issues: Array<{ category, severity, suggestion }>;
    score: 0-100;
    plan_diff_lines: number;
    converged: boolean;
    timestamp: ISO8601;
  }>;
  convergence?: { stable_at_round, final_diff_pct };
  approval: { status: 'pending'|'approved'|'rejected', timestamp?: ISO8601 };
  summary: string;
}

---

Testing Status

• ✅ Unit tests: 862/862 passing
• ✅ Review-plan schema tests: 13/13 passing
• ✅ TypeScript compilation: Clean
• ⏳ End-to-end testing: Pending (Phase 6)
• ⏳ Live job execution: Pending (Phase 6)

---

Next Steps (Phase 6)

1. Create test idea with PLAN_READY status
2. Trigger review job and monitor execution
3. Verify review-log is saved correctly
4. Check IdeaLog entries for PLAN_REVIEW_RESULT
5. Test approval workflow (approve/reject)
6. Verify state transitions (REVIEWING_PLAN → PLAN_REVIEWED)
7. Test UI display of review-log in plan tab
8. Test cancellation mid-review (revert to PLAN_READY)
9. Test error paths (malformed plan_md, parse failures)
10. Staging rollout (24h test with feature flag)

---

Known Limitations

1. No multi-model API calls: Reviews are simulated by Opus (future: direct model switching via API)
2. No codex injection: Docs not auto-loaded (future: inject patterns + architecture docs)
3. No re-review detection: No diff against previous review-logs (future: highlight what changed)
4. Manual review-log edit: Users cannot edit review-log directly (could be added in future)

---

References

• docs/runbooks/review-plan-job.md — Full implementation guide
• lib/idea-prompts/review-plan-job.md — Prompt documentation
• __tests__/review-plan-job.test.ts — Test examples
• CLAUDE.md — Project rules and patterns