# Requirements: Vivi Speech Translator

**Defined:** 2025-01-29
**Core Value:** Vivi posts emojis and others instantly understand her without needing to know what each emoji means.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Message Detection

- [ ] **DETECT-01**: Bot detects when Vivi is communicating via PluralKit webhook proxying
- [ ] **DETECT-02**: Bot ignores non-Vivi messages (no false positives on other members/bots)
- [ ] **DETECT-03**: Bot works in Discord channels and direct messages (DMs)
- [ ] **DETECT-04**: Bot detects Vivi's messages reliably even after edits or reactions

### Emoji Parsing & Translation

- [ ] **TRANS-01**: Bot parses standard emojis (😷, ❌, 2️⃣) from Vivi's messages
- [ ] **TRANS-02**: Bot parses custom Discord server emojis (`:me1:`, `:custom_name:`) from Vivi's messages
- [ ] **TRANS-03**: Bot translates parsed emojis to text and replies automatically (auto mode)
- [ ] **TRANS-04**: Bot composition reads emojis left-to-right and composes natural language translation
- [ ] **TRANS-05**: Bot replies with plain text translation (never emoji-only responses)
- [ ] **TRANS-06**: Bot's response is concise and clear (respects message length limits)

### Teaching System

- [ ] **TEACH-01**: `/teach emoji "meaning"` command allows users to teach new emoji meanings
- [ ] **TEACH-02**: Bot confirms what it learned (shows emoji and meaning back to user)
- [ ] **TEACH-03**: Bot stores emoji meanings globally across all Discord servers
- [ ] **TEACH-04**: `/meaning emoji` command shows the current meaning of an emoji
- [ ] **TEACH-05**: `/correct emoji "new meaning"` command updates incorrect emoji meanings
- [ ] **TEACH-06**: Audit trail tracks who taught/corrected each emoji and when
- [ ] **TEACH-07**: Any user can teach emojis (not restricted to Vivi or admins)

### Unknown Emoji Handling

- [ ] **UNK-01**: When bot encounters unknown emoji, it skips that emoji
- [ ] **UNK-02**: Bot shows translation of known emojis and prompts user to teach unknown ones
- [ ] **UNK-03**: Teaching prompt is accessible (simple command: `/teach emoji "meaning"`)

### Error Handling

- [ ] **ERROR-01**: When bot encounters an error, it reacts with ❌ instead of crashing
- [ ] **ERROR-02**: Bot logs errors for debugging (no message to user)
- [ ] **ERROR-03**: Bot retries failed database operations (exponential backoff)

### Configuration

- [ ] **CONFIG-01**: `/config auto-translate on|off` command toggles automatic translation per server
- [ ] **CONFIG-02**: Default mode is auto (bot translates every Vivi message)
- [ ] **CONFIG-03**: Setting is per-server (each Discord server has its own preference)
- [ ] **CONFIG-04**: Only server admins can change configuration

### Database & Persistence

- [ ] **DB-01**: Global emoji dictionary persists across bot restarts
- [ ] **DB-02**: Emoji meanings shared across all Discord servers (one dictionary)
- [ ] **DB-03**: Per-server configuration persists (auto/on-demand toggle)
- [ ] **DB-04**: Audit trail of teaching actions stored with user ID and timestamp

### Accessibility

- [ ] **A11Y-01**: All bot responses are plain text (no heavy formatting or embeds)
- [ ] **A11Y-02**: `/teach emoji "meaning"` command is simple and short
- [ ] **A11Y-03**: Bot responses are concise (under 3 sentences)
- [ ] **A11Y-04**: Slash commands are used (better keyboard navigation than buttons)
- [ ] **A11Y-05**: Emoji names included in responses for screen readers

### Generalization & Multi-System

- [ ] **GEN-01**: Architecture supports adding other plural systems in future (not Vivi-only hardcoded)
- [ ] **GEN-02**: Emoji dictionary design allows per-system or per-guild overrides (for future v2)
- [ ] **GEN-01**: Code is modular enough for other systems to fork and customize

## v2 Requirements

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

### On-Demand Translation

- **DEMAND-01**: Users can react with 🔤 to request translation (on-demand mode)
- **DEMAND-02**: `/translate message_id` command translates a specific Vivi message

### Advanced Configuration

- **CONFIG-05**: Per-server custom emoji overrides (e.g., server A uses 😊 for "happy", server B uses it for "embarrassed")
- **CONFIG-06**: Per-server emoji moderation (block certain emojis from being taught)

### Analytics & Admin

- **STATS-01**: `/stats` shows frequently-translated emojis per server
- **STATS-02**: `/emoji-list` shows all known emoji meanings with teaching source
- **ADMIN-01**: Server admins can reset emoji meanings to defaults
- **ADMIN-02**: Bot owner can view global statistics (all servers)

### Translation Quality

- **QUALITY-01**: Reaction-based feedback (👍/👎) on translations
- **QUALITY-02**: Bot improves formatting based on feedback patterns

### Multi-Language

- **MULTI-01**: Emoji meanings in multiple languages (future expansion)

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| Real-time chat simulation | Out of scope — this is translation only, not a messaging system |
| Cross-Discord emoji translation | Potential conflicts; focus on Vivi's system meanings only |
| Context-aware inference | Explicit teaching required — meanings don't infer from conversation context |
| Voice/audio output | Translation to text only — no text-to-speech |
| Mobile app | Discord bot only — no standalone app |
| ML-based emoji sentiment | Rule-based only for v1; statistical fallback deferred to future |
| Custom emoji creation | Bot translates existing emojis; doesn't create new ones |
| Message history scanning | Only translates new messages; doesn't retroactively translate old ones |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| DETECT-01 | Phase 1 | Pending |
| DETECT-02 | Phase 1 | Pending |
| DETECT-03 | Phase 1 | Pending |
| DETECT-04 | Phase 2 | Pending |
| TRANS-01 | Phase 2 | Pending |
| TRANS-02 | Phase 2 | Pending |
| TRANS-03 | Phase 2 | Pending |
| TRANS-04 | Phase 2 | Pending |
| TRANS-05 | Phase 2 | Pending |
| TRANS-06 | Phase 2 | Pending |
| TEACH-01 | Phase 3 | Pending |
| TEACH-02 | Phase 3 | Pending |
| TEACH-03 | Phase 3 | Pending |
| TEACH-04 | Phase 3 | Pending |
| TEACH-05 | Phase 3 | Pending |
| TEACH-06 | Phase 3 | Pending |
| TEACH-07 | Phase 3 | Pending |
| UNK-01 | Phase 2 | Pending |
| UNK-02 | Phase 3 | Pending |
| UNK-03 | Phase 3 | Pending |
| ERROR-01 | Phase 2 | Pending |
| ERROR-02 | Phase 5 | Pending |
| ERROR-03 | Phase 5 | Pending |
| CONFIG-01 | Phase 4 | Pending |
| CONFIG-02 | Phase 2 | Pending |
| CONFIG-03 | Phase 4 | Pending |
| CONFIG-04 | Phase 4 | Pending |
| DB-01 | Phase 1 | Pending |
| DB-02 | Phase 2 | Pending |
| DB-03 | Phase 4 | Pending |
| DB-04 | Phase 3 | Pending |
| A11Y-01 | Phase 2 | Pending |
| A11Y-02 | Phase 3 | Pending |
| A11Y-03 | Phase 3 | Pending |
| A11Y-04 | Phase 2 | Pending |
| A11Y-05 | Phase 3 | Pending |
| GEN-01 | Phase 1 | Pending |
| GEN-02 | Phase 4 | Pending |
| GEN-03 | Phase 3 | Pending |

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

---
*Requirements defined: 2025-01-29*
*Last updated: 2025-01-29 after initial definition*