MOPC-Portal/.planning/REQUIREMENTS.md

# Requirements: MOPC — AI Ranking, Advancement & Mentoring

**Defined:** 2026-02-26
**Core Value:** Admins can describe ranking criteria in natural language, the system interprets and ranks projects accordingly, and they can advance the top projects to the next round with one click — all with full override control.

## v1 Requirements

Requirements for this milestone. Each maps to roadmap phases.

### AI Ranking Engine

- [x] **RANK-01**: Admin can write ranking criteria in natural language (free text) for any evaluation round
- [x] **RANK-02**: AI interprets natural-language criteria into structured ranking rules (vote thresholds, score cutoffs, conditional logic)
- [x] **RANK-03**: AI presents parsed rules to admin for review and confirmation before applying (preview mode)
- [x] **RANK-04**: Admin can use quick-rank mode where AI interprets and ranks directly without preview
- [x] **RANK-05**: System ranks projects per CompetitionCategory (STARTUP, BUSINESS_CONCEPT) separately
- [x] **RANK-06**: Ranking considers jury evaluation scores, pass/fail votes, and any criteria defined by admin
- [x] **RANK-07**: AI ranking service anonymizes project data before sending to OpenAI (follows existing anonymization pattern)
- [x] **RANK-08**: Ranking results are stored as snapshots for audit trail (RankingSnapshot model)
- [x] **RANK-09**: Ranking auto-triggers when all jury assignments for a round are completed (all evaluations submitted)
- [x] **RANK-10**: Auto-trigger works retroactively for rounds where all assignments are already complete

### Ranking Dashboard

- [x] **DASH-01**: Admin sees ranked project list per category on the round detail page (new tab)
- [x] **DASH-02**: Admin can drag-and-drop to reorder projects in the ranked list
- [x] **DASH-03**: Drag-and-drop state is isolated from server state to prevent snap-back race conditions
- [x] **DASH-04**: Admin can click a project to see full evaluation data in a side panel (scores, votes, juror comments, pass/fail)
- [x] **DASH-05**: Admin can select "Advance top X" to promote the top N projects to the next round
- [x] **DASH-06**: Admin can batch-reject remaining non-advanced projects
- [x] **DASH-07**: Advance button is disabled until any pending reorder mutations settle

### Email & Notifications

- [ ] **MAIL-01**: Admin can edit email text content for advancement/rejection notifications (follows existing email styling)
- [ ] **MAIL-02**: Email templates support variable insertion ({{firstName}}, {{teamName}}, {{competitionName}}, {{roundName}}, etc.) with simple text editor
- [ ] **MAIL-03**: Variable substitution uses whitelist-only approach (no Handlebars/Mustache engine) to prevent template injection
- [ ] **MAIL-04**: Admin chooses per-batch whether to send advancement email, rejection email, or just update status silently
- [ ] **MAIL-05**: System warns admin if the next round does not have automated welcome emails configured
- [ ] **MAIL-06**: EmailTemplate model stores templates in database, associated with competition/round

### Mentor Management

- [ ] **MENT-01**: Admin can assign mentors to projects during any round type (not just MENTORING rounds)
- [ ] **MENT-02**: Mentor assignments auto-persist across rounds unless the project is eliminated
- [ ] **MENT-03**: Admin can override or change mentor assignments at any time
- [ ] **MENT-04**: AI suggests mentor-project matches based on expertise, with admin confirmation
- [ ] **MENT-05**: System re-validates conflict of interest when mentor assignment carries over to a new round
- [ ] **MENT-06**: Mentor assignment status is visible in the ranking dashboard for context

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Advanced Ranking

- **RANK-V2-01**: Ranking history comparison (compare snapshots across re-rankings)
- **RANK-V2-02**: Export ranking results to CSV/PDF
- **RANK-V2-03**: Multi-language criteria support (French/English auto-detect)

### Advanced Email

- **MAIL-V2-01**: Email template versioning and rollback
- **MAIL-V2-02**: Email preview with sample data before sending
- **MAIL-V2-03**: Email delivery tracking (sent, opened, bounced)

### Advanced Mentoring

- **MENT-V2-01**: Mentor capacity management (max projects per mentor)
- **MENT-V2-02**: Mentor-applicant messaging through the platform
- **MENT-V2-03**: Mentor feedback forms per round

## Out of Scope

| Feature | Reason |
|---------|--------|
| Real-time collaborative ranking | CRDT complexity, single admin typically manages rankings |
| Fully automated advancement without review | Accountability concern — human must confirm |
| WYSIWYG email editor | XSS risk + complexity; Tiptap with variable chips is sufficient |
| Auto-send emails on round transition | Risk of accidental mass-emails in production |
| Award eligibility (Spotlight on Africa) | Separate workflow, later milestone |
| Public-facing ranking results | Admin-only feature, no external visibility needed |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| RANK-01 | Phase 1 | Complete |
| RANK-02 | Phase 1 | Complete |
| RANK-03 | Phase 1 | Complete |
| RANK-04 | Phase 1 | Complete |
| RANK-05 | Phase 1 | Complete |
| RANK-06 | Phase 1 | Complete |
| RANK-07 | Phase 1 | Complete |
| RANK-08 | Phase 1 | Complete |
| RANK-09 | Phase 1 | Complete |
| RANK-10 | Phase 1 | Complete |
| DASH-01 | Phase 2 | Complete |
| DASH-02 | Phase 2 | Complete |
| DASH-03 | Phase 2 | Complete |
| DASH-04 | Phase 2 | Complete |
| DASH-05 | Phase 2 | Complete |
| DASH-06 | Phase 2 | Complete |
| DASH-07 | Phase 2 | Complete |
| MAIL-01 | Phase 3 | Pending |
| MAIL-02 | Phase 3 | Pending |
| MAIL-03 | Phase 3 | Pending |
| MAIL-04 | Phase 3 | Pending |
| MAIL-05 | Phase 3 | Pending |
| MAIL-06 | Phase 3 | Pending |
| MENT-01 | Phase 4 | Pending |
| MENT-02 | Phase 4 | Pending |
| MENT-03 | Phase 4 | Pending |
| MENT-04 | Phase 4 | Pending |
| MENT-05 | Phase 4 | Pending |
| MENT-06 | Phase 4 | Pending |

**Coverage:**
- v1 requirements: 29 total
- Mapped to phases: 29
- Unmapped: 0 ✓

---
*Requirements defined: 2026-02-26*
*Last updated: 2026-02-26 after roadmap creation — all 29 requirements mapped*