mystiatech/Vivi-Speech
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Vivi-Speech/.planning/REQUIREMENTS.md
Dani B 61eb9f960a 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.
2026-01-29 11:05:42 -05:00

175 lines
7.2 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 View Git Blame Copy Permalink