mystiatech/Vivi-Speech
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3e89f67666326e4039bcef750832f5f5f6598708
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

7.2 KiB
Raw Blame History

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