e9e6fadb1d
- Fix ChatBubble to handle non-string content with String() wrapper - Fix API route to use generateText for non-streaming requests - Add @ai-sdk/openai-compatible for non-OpenAI providers (DeepSeek, etc.) - Use Chat Completions API instead of Responses API for compatible providers - Update ChatBubble tests and fix component exports to kebab-case - Remove stale PascalCase ChatBubble.tsx file
71 lines
4.6 KiB
Markdown
71 lines
4.6 KiB
Markdown
# Epic Retrospective
|
|
**Epic:** Epic 2: "The Magic Mirror" - Ghostwriter & Draft Refinement
|
|
**Date:** 2026-01-23
|
|
**Participants:** Max (Dev), Bob (SM), Alice (Principal Engineer)
|
|
|
|
---
|
|
|
|
## 1. Epic Review
|
|
|
|
### Successes (Start doing / Continue doing)
|
|
- **Ghostwriter "Magic Moment":** The transition from chat to the "Draft View" slide-up sheet (Story 2.2) successfully delivered the "Magic Moment" UX. The visual distinction between the casual chat (Inter) and the professional draft (Merriweather) is impactful.
|
|
- **Streaming Architecture:** The implementation of streaming responses for the Ghostwriter (Story 2.1) provides immediate feedback to the user, improving perceived performance.
|
|
- **Refinement Loop:** The conversational refinement flow (Story 2.3) works seamlessly, maintaining context and allowing natural iteration on drafts.
|
|
- **Logic Sandwich Enforcement:** We successfully caught and fixed a critical architecture violation in Story 2.4 (Store accessing DB directly) before it became technical debt. This proves the value of our adversarial code review process.
|
|
- **Local-First Data Boundary:** We maintained strict adherence to keeping user data local (IndexedDB), even while interacting with the LLM API for generation.
|
|
|
|
### Challenges (Stop doing / Improve)
|
|
- **Architecture Violations:** Story 2.4 initially implemented `completeDraft` with restricted DB calls inside the Store, violating our Service Layer pattern.
|
|
- *Root Cause:* Developer convenience/shortcut to avoid passing data through the Service layer.
|
|
- *Fix:* Refactored to `ChatService.approveDraft` to orchestrate DB and Clipboard actions.
|
|
- **Inline Component Definitions:** Story 2.4 implemented the "Copy Button" inline within `DraftActions.tsx` instead of creating the specified `CopyButton.tsx`.
|
|
- *Root Cause:* Missed requirement detail during implementation.
|
|
- *Fix:* Extracted to standalone component during review.
|
|
- **Mocking Streams:** Initial testing for streaming responses (Story 2.1) was flaky due to complex `ReadableStream` mocking.
|
|
- *Fix:* Standardized `mockFetch` pattern in `llm-service.test.ts`.
|
|
|
|
### Key Insights & Lessons Learned
|
|
- **Adversarial Review is Critical:** The code review workflow successfully identified architectural drift that automated linters missed. We must continue this rigorous manual review.
|
|
- **Service Layer as Orchestrator:** The "Logic Sandwich" proves essential for features that touch multiple domains (e.g., Database + Clipboard + UI State). The Service layer is the only place where these should mix.
|
|
- **Component Granularity:** Be vigilant about "inline" components growing too large. Creating dedicated files (like `CopyButton.tsx`) keeps the codebase navigable.
|
|
|
|
---
|
|
|
|
## 2. Metrics & KPI Check-in
|
|
|
|
| Metric | Status | Notes |
|
|
| :------------------- | :----- | :--------------------------------------------------------------- |
|
|
| **Story Completion** | 4 / 4 | All stories (2.1 - 2.4) completed and verified. |
|
|
| **Test Coverage** | High | Critical paths (Draft Service, Chat Store, LLM Service) covered. |
|
|
| **NFR Compliance** | Pass | Local-first boundary respected; UX performance is smooth. |
|
|
| **Bug Count** | 0 | No open bugs. |
|
|
|
|
---
|
|
|
|
## 3. Action Items
|
|
|
|
| Item | Priority | Owner | Status |
|
|
| :----------------------------------- | :------- | :-------- | :------------------------- |
|
|
| **Review Epic 3 Architecture** | High | Architect | Pending |
|
|
| **Ensure 'Sessions' Table Indexing** | Medium | Dev | Pending (for Epic 3) |
|
|
| **Refactor Test Mocks to Helper** | Low | Dev | Open (Consider for Epic 3) |
|
|
|
|
---
|
|
|
|
## 4. Next Epic Preview
|
|
|
|
**Epic 3: "The Memory Palace" - History & Persistence**
|
|
*Goal:* Enable users to browse, search, and manage their past chat sessions and drafts.
|
|
|
|
**Critical Considerations:**
|
|
- **IndexedDB Performance:** We will be loading lists of sessions. We need to ensure correct indexing in `schema.ts`.
|
|
- **Search-on-Type:** Implementing performant local search (Dexie `startsWith` or `AnyOf`) for the history sidebar.
|
|
- **Virtualization:** The history list might grow long; consider `react-window` if performance degrades.
|
|
- **Data Migration:** Ensure backward compatibility if we change the schema for Epic 3.
|
|
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **Architectural Reminder for Epic 3:**
|
|
> As we build the History UI, ensure strict separation between the `HistoryService` (data fetching) and the `HistorySidebar` (UI). Do not leak Dexie queries into React components.
|