diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..f77b95b --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,401 @@ +# Roadmap: Vivi Speech Translator + +**Vision:** Discord bot that translates Vivi's emoji communication into text so her community understands her instantly. + +**Phases:** 5 | **Requirements Covered:** 33/33 | **Coverage:** 100% ✓ + +--- + +## Phase Overview + +| Phase | Name | Goal | Requirements | Success Criteria | +|-------|------|------|--------------|------------------| +| 1 | Foundation | Reliably detect Vivi's PluralKit messages and set up database | DETECT-01, DETECT-02, DETECT-03, DB-01, GEN-01 | 4 | +| 2 | Translation Engine | Parse emojis and translate to text with auto mode | TRANS-01, TRANS-02, TRANS-03, TRANS-04, TRANS-05, TRANS-06, DETECT-04, UNK-01, ERROR-01, CONFIG-02, A11Y-01, A11Y-04, DB-02 | 5 | +| 3 | Teaching System | Let users teach emoji meanings via simple commands | TEACH-01, TEACH-02, TEACH-03, TEACH-04, TEACH-05, TEACH-06, TEACH-07, UNK-02, UNK-03, A11Y-02, A11Y-03, A11Y-05, DB-04, GEN-03 | 5 | +| 4 | Configuration & Scaling | Add per-server settings and advanced features | CONFIG-01, CONFIG-03, CONFIG-04, DB-03, GEN-02 | 4 | +| 5 | Production Polish | Hardening, logging, and reliability | ERROR-02, ERROR-03 | 3 | + +--- + +## Phase Breakdown + +### Phase 1: Foundation (Weeks 1-2) + +**Goal:** Reliably detect when Vivi is communicating via PluralKit and establish database infrastructure. + +**Why First:** +- PluralKit detection is a load-bearing component (foundation for all translation) +- Database setup enables all future phases +- Demonstrates proof of concept that detection works reliably + +**Requirements Covered:** +- DETECT-01: Bot detects Vivi via PluralKit webhook +- DETECT-02: Bot ignores non-Vivi messages (no false positives) +- DETECT-03: Bot works in channels and DMs +- DB-01: Global emoji dictionary persists +- GEN-01: Architecture supports multiple systems (not Vivi-only hardcoded) + +**Success Criteria:** + +1. Bot reliably logs "Vivi detected" when she sends a test message with PluralKit webhook +2. Bot ignores messages from other system members (no false positives on non-Vivi webhooks) +3. Database (SQLite for MVP) initializes on bot startup without errors +4. Emoji dictionary table and server configuration table created and readable + +**Key Implementation Tasks:** +- Set up discord.py client with correct intents (GUILDS, MEMBERS) +- Implement webhook detection (check message.webhook_id) +- Implement PluralKit API query to verify member_id matches Vivi's ID +- Initialize SQLite database with emoji_dictionary and server_config tables +- Test edge cases: Vivi's message edits, reactions, message deletes, DM context + +**Architecture Notes:** +- Use aiosqlite for async database access (MVP) +- Cache PluralKit member list with 1-hour TTL to reduce API calls +- Use nacl.signing to verify PluralKit webhook signatures where possible +- Design message handler as a cog (modular for future systems) + +**Risks & Mitigations:** +- Risk: PluralKit API rate limits during initialization (10/sec) + - Mitigation: Implement webhook dispatch instead of polling; cache member list +- Risk: Message content intent denied by Discord + - Mitigation: Design for slash commands as primary path; message content as optional enhancement + +**Dependencies:** None (Phase 1 is the foundation) + +--- + +### Phase 2: Translation Engine (Weeks 3-4) + +**Goal:** Parse emoji sequences from Vivi's messages and translate to text automatically. + +**Why Second:** +- Builds on Phase 1's detection foundation (no detection = nothing to translate) +- Delivers core user value: Vivi posts, others understand +- Unblocks Phase 3 (teaching system requires working translation to be useful) +- Enables MVP validation with early users + +**Requirements Covered:** +- TRANS-01: Parse standard emojis (😷, ❌, 2️⃣) +- TRANS-02: Parse custom Discord emojis (`:me1:`, etc.) +- TRANS-03: Translate and reply automatically (auto mode) +- TRANS-04: Read left-to-right composition (preserve emoji order) +- TRANS-05: Plain text responses only (no emoji-only translations) +- TRANS-06: Concise, clear responses (respects message length limits) +- DETECT-04: Reliably detect edits and reactions on Vivi messages +- UNK-01: Skip unknown emojis (only translate known ones) +- ERROR-01: React with ❌ on translation errors (graceful failure) +- CONFIG-02: Default mode is auto (bot translates every Vivi message) +- A11Y-01: Plain text accessible format (no heavy formatting) +- A11Y-04: Use slash commands (better keyboard navigation than buttons) +- DB-02: Emoji meanings shared across all Discord servers (one global dictionary) + +**Success Criteria:** + +1. Bot translates `:me1:😷 2️⃣` sequence to "Vivi is sick" and shows which emoji are unknown +2. Bot translates multi-emoji sequences (5+ emojis) correctly while preserving order and composition +3. Bot response is plain text, under 3 sentences (accessibility for dysgraphia) +4. Unknown emojis are skipped with gentle prompt to teach ("Unknown emoji; run `/teach emoji meaning`") +5. If database query fails, bot reacts with ❌ instead of crashing or spamming errors + +**Key Implementation Tasks:** +- Use `emoji` library 2.11.0 for standard emoji parsing (Unicode 15.0 support) +- Regex pattern for custom Discord emoji detection (`:emoji_name:`) +- Dictionary lookup function (emoji → meaning) with O(1) query time +- Translation composition function (assemble meanings into natural language) +- Error handler that reacts with ❌ and logs error +- Message edit detection (track message ID, compare old vs new emoji) +- Test emoji edge cases: skin tone modifiers, ZWJ sequences, variation selectors + +**Architecture Notes:** +- Translation engine should be stateless (all state in database) +- Compose natural language by concatenating meanings when simple, or identifying patterns (subject + descriptor + descriptor) +- Handle emoji variants correctly (normalize input with NFD if needed) +- Cache frequently-translated emoji in memory (optional for Phase 2; may add in Phase 4) +- Response format: "Vivi says: [translation]" for clarity + +**Risks & Mitigations:** +- Risk: Emoji edge cases (combining characters, ZWJ) causing parse failures + - Mitigation: Comprehensive test suite with Unicode 15.0 samples; use emoji library instead of manual regex +- Risk: Bot floods channel with translations (rate limiting) + - Mitigation: Track requests per guild; implement cooldown if needed (Phase 4+) +- Risk: Message edits race condition (bot editing response while Vivi edits message) + - Mitigation: Post new translation instead of editing; queue requests with small delay if race detected + +**Dependencies:** Phase 1 (detection + database) + +--- + +### Phase 3: Teaching System (Weeks 5-6) + +**Goal:** Enable users to teach the bot new emoji meanings via simple commands. + +**Why Third:** +- Requires working translation from Phase 2 (teaching emoji that don't translate yet is the whole point) +- Enables the learning system (core differentiator: bot becomes more useful as community teaches it) +- Makes bot valuable to Vivi's community: they drive growth, not predefined dictionary +- Addresses dysgraphia accessibility: teaching interface must be ultra-simple + +**Requirements Covered:** +- TEACH-01: `/teach emoji "meaning"` command +- TEACH-02: Bot confirms what it learned (shows emoji and meaning) +- TEACH-03: Meanings stored globally (shared across all servers) +- TEACH-04: `/meaning emoji` query command +- TEACH-05: `/correct emoji "new meaning"` update command +- TEACH-06: Audit trail (who, what, when for all changes) +- TEACH-07: Anyone can teach (no admin restrictions, but logged for accountability) +- UNK-02: Skip unknowns; prompt to teach (gentle, actionable prompt) +- UNK-03: Teaching prompt is accessible (simple command: `/teach emoji "meaning"`) +- A11Y-02: Simple command syntax (one-liner, no complex structure) +- A11Y-03: Concise responses (under 2 sentences; important for dysgraphia) +- A11Y-05: Emoji names in responses (for screen readers; show Unicode name) +- DB-04: Audit trail storage (emoji_id, old_meaning, new_meaning, user_id, timestamp) +- GEN-03: Modular code for other systems (teaching system not Vivi-specific) + +**Success Criteria:** + +1. User runs `/teach 🎭 "happy performance"`, bot confirms "Taught: 🎭 = happy performance" with emoji shown +2. Next time Vivi uses 🎭, bot translates it correctly in the translation engine (cache or DB lookup) +3. User runs `/meaning 🎭`, bot replies with current meaning (or "Unknown emoji") +4. User runs `/correct 🎭 "joyful"`, meaning updates and audit trail records who changed it and when +5. `/teach` command fails gracefully if emoji is invalid, meaning is empty, or meaning is too long (with helpful error message) + +**Key Implementation Tasks:** +- Discord.py slash command handler for `/teach emoji "meaning"` +- Input validation: emoji exists, meaning is 1-200 characters, no excessive punctuation +- Database insert into emoji_dictionary with user_id and timestamp +- `/meaning emoji` query command with error handling +- `/correct emoji "new meaning"` update command with audit trail +- Confirmation messages that show emoji visually (e.g., "🎭" not "PERFORMING_ARTS") +- Audit trail table: emoji_id, old_meaning, new_meaning, user_id, timestamp, action_type +- Permission checks: log who taught what, but don't restrict based on role (accessibility) +- Test that emojis can be taught, corrected, queried in rapid succession + +**Architecture Notes:** +- Teaching commands should be accessible to all users (not admin-only; logged for accountability) +- Confirmation should always show the emoji visually (immediate visual feedback) +- Responses must be short (<2 sentences) for dysgraphia accessibility +- Audit trail enables future `/undo` feature (deferred to v2) +- Global dictionary shared across servers; per-server overrides deferred to Phase 4+ + +**Risks & Mitigations:** +- Risk: Users teach wrong/inappropriate meanings (spam, trolling) + - Mitigation: Audit trail allows corrections; log all changes; v2 adds moderation if needed +- Risk: Teaching interface too complex for Vivi (with dysgraphia) + - Mitigation: Ultra-simple one-liner syntax; visual confirmation with emoji; test with Vivi early +- Risk: Conflicting emoji meanings across servers + - Mitigation: Global dictionary is by design (shared knowledge); document this limitation; v2 adds per-server overrides + +**Dependencies:** Phase 2 (translation must work so teaching has value) + +--- + +### Phase 4: Configuration & Scaling (Week 7) + +**Goal:** Add per-server settings and prepare for scaling. + +**Why Fourth:** +- Builds on Phases 1-3 foundation (all core features working) +- Enables server customization without breaking global emoji dictionary +- Prepares architecture for multi-server scaling and future systems +- Adds operator controls (config commands) + +**Requirements Covered:** +- CONFIG-01: `/config auto-translate on|off` toggle per server +- CONFIG-03: Per-server persistence (setting survives bot restart) +- CONFIG-04: Admin-only changes (permission check on `/config` command) +- DB-03: Per-server config table +- GEN-02: Architecture supports per-system overrides (design for future multi-system) + +**Success Criteria:** + +1. Server admin runs `/config auto-translate off`, future Vivi messages don't auto-translate (bot is silent by default) +2. Another server has auto enabled; both work independently (no crosstalk) +3. Setting persists across bot restart (database query returns correct value) +4. Non-admin user runs `/config auto-translate on`, bot rejects with "Admin only" message +5. Default for new servers is auto mode enabled (true by default in code) + +**Key Implementation Tasks:** +- `/config auto-translate ` slash command +- Permission check (admin-only; use discord.py's default_member_permissions) +- server_config table update/insert (guild_id as PK, auto_translate as boolean) +- Modify message handler to check per-guild setting before auto-translating +- Implement on-demand mode placeholder (manual translation via `/translate` command; full reaction-based mode deferred to v2) +- Cache per-server settings for performance (1-minute TTL) +- Test: change setting, verify immediate effect; verify effect persists after restart + +**Architecture Notes:** +- On-demand mode: bot only replies if explicitly requested (stored in DB but not fully implemented in v1) +- Per-server config indexed by guild_id for O(1) lookup +- Cache server settings in memory with TTL to avoid DB hammering +- Design allows per-system overrides in future (deferred to v2) + +**Risks & Mitigations:** +- Risk: Per-server override conflicts if not careful + - Mitigation: v2 design allows per-system overrides; v1 focuses on global dictionary with server-level auto/on-demand toggle +- Risk: Config command is confusing to admins + - Mitigation: Clear help text; only two options (on/off); simple feedback message + +**Dependencies:** Phases 1-3 (all features working; config customizes them) + +--- + +### Phase 5: Production Polish (Week 8+) + +**Goal:** Production hardening, logging, error handling, and monitoring. + +**Why Last:** +- Follows all feature phases (features must be complete before hardening) +- Improves reliability and debuggability (enables diagnosis of issues in production) +- Prepares for public adoption by other systems or larger communities + +**Requirements Covered:** +- ERROR-02: Bot logging for debugging (structured JSON logs) +- ERROR-03: Exponential backoff for failed DB operations and API calls + +**Success Criteria:** + +1. Structured JSON logs written to file (timestamp, level, message, context, duration) with rotation +2. Bot retries failed PluralKit API calls (exponential backoff: 1s, 2s, 4s, 8s with jitter) +3. Bot retries failed database operations (same backoff strategy; max 5 attempts) +4. Unhandled exceptions caught and logged (no spam in user channels; clear error reaction) +5. All error logs include context (guild_id, user_id, emoji attempted, operation type) + +**Key Implementation Tasks:** +- Set up Python logging with JSON format (structlog or custom JSON formatter) +- Implement retry logic with asyncio.sleep backoff for PluralKit API calls +- Implement retry logic with backoff for database queries +- Add global exception handler (on_error in discord.py) +- Comprehensive error documentation (what errors mean, how to diagnose) +- Testing edge cases: rate limits, database disconnects, webhook timing issues, missing intents +- Optional: Sentry integration for error tracking (recommended but not required for v1) + +**Architecture Notes:** +- Async error handling must not block the event loop +- Retry logic should use exponential backoff with jitter (avoid thundering herd) +- Logs should include PluralKit request context (duration, status code, member_id) for debugging +- Log all emoji lookups (emoji, result: found/unknown) to identify teaching gaps + +**Risks & Mitigations:** +- Risk: Logging overhead impacts performance + - Mitigation: Async logging; batch writes; exclude noisy operations (every emoji lookup) +- Risk: Backoff strategy causes noticeable delays when DB is down + - Mitigation: Set reasonable max wait (8s); fail fast if max attempts exceeded; user sees ❌ reaction quickly + +**Dependencies:** Phases 1-4 (all features working; Phase 5 hardens them) + +--- + +## Dependency Chain + +``` +Phase 1: Foundation (Discord client, PluralKit detection, database) + ↓ +Phase 2: Translation (emoji parsing, lookups, auto-translation) + ↓ +Phase 3: Teaching (commands to add/update meanings; audit trail) + ↓ +Phase 4: Configuration (per-server auto/on-demand toggle) + ↓ +Phase 5: Polish (logging, retry logic, production hardening) +``` + +**Critical Path:** Phase 1 → Phase 2 → Phase 3 (core value) +**Optional Path:** Phase 4 (customization), Phase 5 (hardening) + +--- + +## Requirement Coverage Summary + +**Total v1 Requirements:** 33 +**Mapped to Phases:** 33 +**Unmapped:** 0 ✓ + +**Coverage by Category:** +- Message Detection (DETECT-01 through DETECT-04): 4/4 mapped → Phases 1, 2 +- Emoji Parsing & Translation (TRANS-01 through TRANS-06): 6/6 mapped → Phase 2 +- Teaching System (TEACH-01 through TEACH-07): 7/7 mapped → Phase 3 +- Unknown Emoji Handling (UNK-01 through UNK-03): 3/3 mapped → Phases 2, 3 +- Error Handling (ERROR-01 through ERROR-03): 3/3 mapped → Phases 2, 5 +- Configuration (CONFIG-01 through CONFIG-04): 4/4 mapped → Phases 2, 4 +- Database & Persistence (DB-01 through DB-04): 4/4 mapped → Phases 1, 2, 3, 4 +- Accessibility (A11Y-01 through A11Y-05): 5/5 mapped → Phases 2, 3 +- Generalization & Multi-System (GEN-01 through GEN-03): 3/3 mapped → Phases 1, 3, 4 + +--- + +## Key Decisions & Rationale + +| Decision | Rationale | Phase | +|----------|-----------|-------| +| Global emoji dictionary | Vivi's emoji language is consistent across communities; other systems benefit from shared knowledge | 1-3 | +| Learning-based system | Vivi uses many emojis; manual mapping would be unsustainable. Bot learns when taught. | 3 | +| PluralKit webhook integration | Standard plural system tool; webhook dispatch is instant and free (vs API polling) | 1 | +| Auto mode as default | Translates automatically; more accessible for Vivi (no extra action needed) | 2, 4 | +| Per-server configuration | Different communities have different needs (auto vs on-demand); can customize without breaking shared dictionary | 4 | +| Plain text responses only | Accessibility for dysgraphia; avoids confusion with Discord formatting | 2 | +| No context inference | Meanings learned explicitly; avoids false positives and keeps system transparent | Out of Scope | +| Five-phase structure | Mirrors research recommendations; each phase delivers measurable value | All | + +--- + +## Key Metrics & Success Indicators + +**Per Phase:** +- Phase 1: >99% detection accuracy, zero false positives in testing +- Phase 2: <500ms response time, 100% parse accuracy on Unicode 15.0 emoji +- Phase 3: Teaching interface usable by Vivi (requires user testing), 50+ emoji taught in beta week +- Phase 4: Settings persist across restart, multi-server support verified +- Phase 5: <0.1% error rate, all failures logged and alertable + +**Overall:** +- Time to MVP (Phases 1-2): 3-4 weeks +- Time to v1 (Phases 1-5): 5-6 weeks +- Requirements per phase: 3-7 (manageable scope) +- Value delivered: Incremental (each phase adds core functionality) + +--- + +## Known Limitations & v2+ Backlog + +**Intentionally v2+:** +- Per-server emoji overrides (global dictionary only in v1) +- Reaction-based on-demand translation (slash command placeholder only) +- Analytics dashboard (`/stats`, `/emoji-list`) +- Moderation UI (flag/approve/reject meanings) +- Multi-language emoji meanings +- Support for other plural systems beyond PluralKit (architecture designed for it, not enabled) + +--- + +## Implementation Notes + +**Tech Stack:** +- discord.py 2.6.4 (async-first, native slash commands) +- SQLite MVP (zero setup; migrate to PostgreSQL if >1000 emoji) +- aiosqlite (async database access) +- emoji 2.11.0 (Unicode 15.0 support) +- pydantic 2.5.0 (data validation) +- Railway Cloud for hosting (free tier for MVP) + +**Code Organization:** +- `bot.py` - Main discord.py client, event loop +- `cogs/detection.py` - Message event handler, PluralKit detection +- `cogs/translation.py` - Emoji parsing, dictionary lookup, composition +- `cogs/teaching.py` - `/teach`, `/meaning`, `/correct` commands +- `cogs/config.py` - `/config` command, per-server settings +- `database.py` - SQLAlchemy ORM, async queries +- `logging.py` - Structured JSON logging, retry logic + +**Testing Strategy:** +- Unit tests: emoji parsing, dictionary lookups, composition +- Integration tests: PluralKit detection with mock webhooks +- Accessibility tests: response length, emoji names for screen readers +- Load tests: 100+ servers, 1000+ emoji, response times + +--- + +**Roadmap created: 2025-01-29** +**Ready for Phase 1 planning** +**Depth: Quick (5 phases, natural boundaries)** diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..3b73b5d --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,204 @@ +# State: Vivi Speech Translator + +**Reference:** See `.planning/PROJECT.md` for full project context + +**Core Value:** Vivi posts emojis and others instantly understand her without needing to know what each emoji means. + +**Last Updated:** 2025-01-29 + +--- + +## Current Position + +**Phase:** Roadmap complete, ready for Phase 1 planning + +**Focus:** Foundation (PluralKit detection + database setup) + +**Timeline:** 5-6 weeks to v1 (33 requirements, 5 phases) + +--- + +## Project Status + +| Aspect | Status | Notes | +|--------|--------|-------| +| **Requirements** | 33 defined ✓ | All v1 requirements mapped to phases | +| **Research** | Complete ✓ | Stack, Features, Architecture, Pitfalls synthesized | +| **Roadmap** | Complete ✓ | 5 phases, 100% coverage, dependencies identified | +| **Phase 1 Plan** | Awaiting | Ready to run `/gsd:plan-phase 1` | +| **Team** | 1 person (user) + Claude | Solo developer + AI pair programming | + +--- + +## Coverage Summary + +**v1 Requirements:** 33 total +- Message Detection: 4 (DETECT-01 through DETECT-04) +- Emoji Parsing & Translation: 6 (TRANS-01 through TRANS-06) +- Teaching System: 7 (TEACH-01 through TEACH-07) +- Unknown Emoji Handling: 3 (UNK-01 through UNK-03) +- Error Handling: 3 (ERROR-01 through ERROR-03) +- Configuration: 4 (CONFIG-01 through CONFIG-04) +- Database & Persistence: 4 (DB-01 through DB-04) +- Accessibility: 5 (A11Y-01 through A11Y-05) +- Generalization: 3 (GEN-01 through GEN-03) + +**Phase Mapping:** +- Phase 1 (Foundation): 5 requirements +- Phase 2 (Translation Engine): 13 requirements +- Phase 3 (Teaching System): 14 requirements +- Phase 4 (Configuration): 5 requirements +- Phase 5 (Polish): 2 requirements + +**Coverage:** 100% ✓ (all 33 mapped, no orphans) + +--- + +## Roadmap at a Glance + +``` +Phase 1: Foundation (Weeks 1-2) + Goal: Detect Vivi via PluralKit, set up database + Success: >99% detection accuracy, zero false positives + +Phase 2: Translation Engine (Weeks 3-4) + Goal: Parse emojis, translate to text, auto-translate + Success: <500ms response, 100% Unicode emoji parse accuracy + +Phase 3: Teaching System (Weeks 5-6) + Goal: Let users teach emoji meanings via simple commands + Success: Teaching interface usable, 50+ emoji taught in beta + +Phase 4: Configuration & Scaling (Week 7) + Goal: Per-server auto/on-demand toggle + Success: Settings persist, multi-server support verified + +Phase 5: Production Polish (Week 8+) + Goal: Logging, retry logic, production hardening + Success: <0.1% error rate, all failures logged +``` + +--- + +## Key Decisions Made + +1. **Global emoji dictionary** (not per-server) — Shared knowledge across communities; per-server overrides defer to v2 +2. **Learning-based system** — Users teach emoji meanings; no manual mapping +3. **Webhook dispatch for PluralKit** — Instant (vs API polling); free and efficient +4. **Auto mode as default** — More accessible for Vivi (no extra action) +5. **Plain text responses only** — Accessibility for dysgraphia +6. **Five-phase structure** — Each phase delivers measurable value + +--- + +## Known Risks & Mitigations + +| Risk | Severity | Phase | Mitigation | +|------|----------|-------|-----------| +| PluralKit detection unreliable | CRITICAL | 1 | Webhook verification + API validation; comprehensive testing | +| Teaching interface too complex | HIGH | 3 | Ultra-simple syntax; visual confirmation; test with Vivi | +| Emoji parsing edge cases | MEDIUM | 2 | Use emoji library; test Unicode 15.0 samples | +| Rate limiting impacts | MEDIUM | 2+ | Cache emoji; batch lookups; backoff strategy | +| Dictionary quality degrades | HIGH | 3+ | Audit trail; input validation; flag conflicts | + +--- + +## Upcoming Milestones + +**Phase 1 Planning** (Next: `/gsd:plan-phase 1`) +- Create detailed execution plan for Foundation phase +- Derive must-haves from success criteria +- Define acceptance tests + +**Phase 1 Delivery** (Weeks 1-2) +- PluralKit detection working >99% accuracy +- Database initialized and queryable +- Proof of concept: bot logs Vivi's messages + +**Phase 2 Delivery** (Weeks 3-4) +- Emoji parsing and translation working +- Auto-translate mode enabled +- MVP ready for early user testing + +**Phase 3 Delivery** (Weeks 5-6) +- Teaching system accessible to Vivi +- 50+ emoji taught by community +- Core value delivered: "Vivi posts, others understand" + +--- + +## Implementation Context + +**Tech Stack:** +- discord.py 2.6.4 (Python async Discord bot framework) +- SQLite MVP → PostgreSQL for production +- aiosqlite (async database) +- emoji 2.11.0 (Unicode support) +- Railway Cloud (free tier hosting) + +**Code Location:** To be initialized in Phase 1 planning + +**Database Location:** SQLite for MVP; will be in project root or `.data/` directory + +**Hosting:** Railway Cloud free tier ($0-5/month for MVP) + +--- + +## Communication & Decisions + +**User Input Needed:** +- Vivi's teaching interface preferences (syntax, visual feedback, response length) +- Exact emoji coverage (standard + custom Discord emoji examples) +- Moderation preferences (who can teach, conflict resolution) + +**Architecture Locked In:** +- Global emoji dictionary (v1) with per-system overrides planned for v2 +- PluralKit webhook detection over API polling +- discord.py 2.6.4 with slash commands as primary interface + +**Open for Discussion:** +- Response format preferences (e.g., "Vivi: sick" vs "Vivi is sick") +- Caching strategy (hot emoji in memory vs all DB lookups) +- Logging verbosity (debug level for early phases) + +--- + +## Progress Tracker + +**Completed:** +- ✓ Research synthesis (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md) +- ✓ Requirements definition (33 v1 requirements) +- ✓ Roadmap creation (5 phases, 100% coverage) +- ✓ Phase-level success criteria (observable user behaviors) + +**In Progress:** +- → Phase 1 planning (breakdown into executable tasks) + +**Pending:** +- Vivi interview for UX validation (Phase 3) +- Phase 1 implementation +- Early user testing (post-Phase 2) +- Performance profiling (post-Phase 3) + +--- + +## Next Steps + +1. **Review ROADMAP.md** — Confirm 5-phase structure and dependencies +2. **Run `/gsd:plan-phase 1`** — Create execution plan for Foundation +3. **Initialize Phase 1 code** — Discord client, PluralKit detection, database +4. **Get Vivi input** — Teaching interface preferences (Phase 3 planning) + +--- + +**Status:** Ready for Phase 1 planning + +**Confidence Level:** ⭐⭐⭐ HIGH (research complete, requirements clear, stack proven) + +**Blockers:** None — proceeding to Phase 1 planning + +--- + +*Generated: 2025-01-29* +*Roadmap: .planning/ROADMAP.md* +*Requirements: .planning/REQUIREMENTS.md*