6.1 KiB
6.1 KiB
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
- RANK-01: Admin can write ranking criteria in natural language (free text) for any evaluation round
- RANK-02: AI interprets natural-language criteria into structured ranking rules (vote thresholds, score cutoffs, conditional logic)
- RANK-03: AI presents parsed rules to admin for review and confirmation before applying (preview mode)
- RANK-04: Admin can use quick-rank mode where AI interprets and ranks directly without preview
- RANK-05: System ranks projects per CompetitionCategory (STARTUP, BUSINESS_CONCEPT) separately
- RANK-06: Ranking considers jury evaluation scores, pass/fail votes, and any criteria defined by admin
- RANK-07: AI ranking service anonymizes project data before sending to OpenAI (follows existing anonymization pattern)
- RANK-08: Ranking results are stored as snapshots for audit trail (RankingSnapshot model)
- 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 | Complete |
| DASH-01 | Phase 2 | Complete |
| 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