docs: define v1 requirements
33 requirements across 9 categories: - Message detection & translation (6) - Teaching system (7) - Unknown emoji handling (3) - Error handling (3) - Configuration (2) - Database (4) - Accessibility (5) - Generalization (3) All v1 requirements mapped to phases 1-5.
This commit is contained in:
Dani B
174
.planning/REQUIREMENTS.md
Normal file
174
.planning/REQUIREMENTS.md
Normal file
@@ -0,0 +1,174 @@
|
|||||||
|
# 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*
|
||||||
Reference in New Issue
Block a user