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 ✅
- [x] Added `plan_review_log` (Json) and `reviewed_at` (DateTime) fields to Idea model
- [x] Added `REVIEWING_PLAN`, `PLAN_REVIEW_FAILED`, `PLAN_REVIEWED` to IdeaStatus enum
- [x] Added `IDEA_REVIEW_PLAN` to ClaudeJobKind enum
- [x] Added `PLAN_REVIEW_RESULT` to IdeaLogType enum
- [x] Created migration `20260514000000_add_review_plan_support`
- [x] Synchronized both Prisma schemas (main repo + scrum4me-mcp)
- [x] 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 ✅
- [x] Created `update_idea_plan_reviewed` MCP tool
- [x] Implemented transaction-safe database updates
- [x] Added error handling and access control
- [x] Registered tool in MCP server index
- [x] Type-safe Zod input validation

### Phase 3: Server Actions & UI Components ✅
- [x] Created `startReviewPlanJobAction()` server action
- [x] Updated `cancelIdeaJobAction()` for IDEA_REVIEW_PLAN
- [x] Updated status transition rules in `lib/idea-status.ts`
- [x] Added status colors and labels for new statuses
- [x] Updated job-card and jobs-column to display IDEA_REVIEW_PLAN
- [x] Updated idea-timeline to display PLAN_REVIEW_RESULT log entries

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

### Phase 5: ReviewLogViewer UI Component ✅
- [x] Created `components/ideas/review-log-viewer.tsx` component
- [x] Integrated component into idea page
- [x] Display review-log in plan tab with convergence metrics
- [x] Show round-by-round issues and scores
- [x] Approval status display with proper styling
- [x] Updated idea page to load and pass `plan_review_log`
- [x] TypeScript compilation successful

### Phase 6: Integration & Rollout 🔄 (In Progress)
- [x] ✅ 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

```typescript
{
  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