128 lines
6.1 KiB
Markdown
128 lines
6.1 KiB
Markdown
|
# 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)
|
||
|
|
- [ ] **RANK-10**: Auto-trigger works retroactively for rounds where all assignments are already complete
|
||
|
|
|
||
|
|
### Ranking Dashboard
|
||
|
|
|
||
|
|
- [ ] **DASH-01**: Admin sees ranked project list per category on the round detail page (new tab)
|
||
|
|
- [ ] **DASH-02**: Admin can drag-and-drop to reorder projects in the ranked list
|
||
|
|
- [ ] **DASH-03**: Drag-and-drop state is isolated from server state to prevent snap-back race conditions
|
||
|
|
- [ ] **DASH-04**: Admin can click a project to see full evaluation data in a side panel (scores, votes, juror comments, pass/fail)
|
||
|
|
- [ ] **DASH-05**: Admin can select "Advance top X" to promote the top N projects to the next round
|
||
|
|
- [ ] **DASH-06**: Admin can batch-reject remaining non-advanced projects
|
||
|
|
- [ ] **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 | Pending |
|
||
|
|
| DASH-01 | Phase 2 | Pending |
|
||
|
|
| DASH-02 | Phase 2 | Pending |
|
||
|
|
| DASH-03 | Phase 2 | Pending |
|
||
|
|
| DASH-04 | Phase 2 | Pending |
|
||
|
|
| DASH-05 | Phase 2 | Pending |
|
||
|
|
| DASH-06 | Phase 2 | Pending |
|
||
|
|
| DASH-07 | Phase 2 | Pending |
|
||
|
|
| 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*
|