Brachnha/brachnha-insight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Brachnha Insight project setup

Browse Source 
- Next.js 14+ with App Router and TypeScript
- Tailwind CSS and ShadCN UI styling
- Zustand state management
- Dexie.js for IndexedDB (local-first data)
- Auth.js v5 for authentication
- BMAD framework integration

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Max
2026-01-26 12:28:43 +07:00
commit 3fbbb1a93b
812 changed files with 150531 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
_bmad-output/planning-artifacts/architecture.md Normal file
View File

@@ -0,0 +1,365 @@
---
stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
inputDocuments:
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/prd.md
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
workflowType: 'architecture'
project_name: 'Test01'
user_name: 'Max'
date: '2026-01-21'
status: 'complete'
completedAt: '2026-01-21'
---
# Architecture Decision Document
_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._
## Project Context Analysis
### Requirements Overview
**Functional Requirements:**
- **Dual-Agent Pipeline:** Core architectural pattern involving a "Teacher" agent for elicitation and a "Ghostwriter" agent for content generation.
- **PWA / Offline Capability:** "Local-First" architecture is mandatory. Must support full "Venting" session offline with a **Client-Side Transaction Log** to queue actions safely.
- **Chat-to-Artifact Transformation:** Distinct UI modes for Input (Chat) vs. Output (Card/Article).
- **History & Persistence:** Local storage (IndexedDB) of all chat logs and generated drafts. Privacy-first data handling.
**Non-Functional Requirements:**
- **Performance:** Low latency (<3s Response, <1.5s TTI). **Client-Side Rendering (CSR)** prioritized for Chat Views to avoid hydration mismatches.
- **Privacy:** 100% Client-Side storage for MVP. No user content sent to cloud persistence.
- **Security:** **Client-Side Key Management** (BYOD). User's API key stored locally and used directly from browser. Optional CORS proxy may be configured if provider doesn't support browser requests.
- **Reliability:** Service Worker caching for offline app shell and aggressive local auto-saving.
**Scale & Complexity:**
- **Primary Domain:** Mobile-First PWA (React/Next.js).
- **Complexity Level:** Medium. (State complexity is high due to offline sync and dual-agent interaction).
- **Estimated Architectural Components:** ~8 key components (Chat Engine, Agent Orchestrator, Storage Layer, Sync Manager, UI Shell, Draft Renderer, Global State Manager, API Proxy).
### Technical Constraints & Dependencies
- **Platform:** Web (PWA) targeting Mobile Safari and Chrome on Android.
- **Stack Preference:** Next.js + Tailwind + ShadCN UI.
- **State Management:** **Global State Manager** (e.g., Zustand) required to decouple "Session State" from "UI View" (handling the slide-up draft view).
- **Storage:** IndexedDB (via wrapper) is the primary source of truth.
### Cross-Cutting Concerns Identified
- **Offline Sync & State Management:** Robust handling of the "Sync Queue" to prevent data loss during connection drops.
- **Theming:** Consistent "Morning Mist" theme application.
- **Agent Orchestration:** Managing the conversational state (Teacher vs. Ghostwriter mode).
- **Error Handling:** Graceful degradation when LLM API fails.
## Starter Template Evaluation
### Primary Technology Domain
**Web Application (PWA)** - Focused on "Local-First" Mobile Experience.
### Starter Options Considered
1. **T3 Stack (`create-t3-app`)**
* *Pros:* Best-in-class type safety.
* *Cons:* Heavily optimized for Server-Side Logic (tRPC/Prisma) which conflicts with our "Offline/Local-First" requirement.
2. **Taxonomy (ShadCN Reference)**
* *Pros:* Excellent reference for content apps.
* *Cons:* Too complex/bloated for a focused "Venting" utility.
3. **Standard Next.js + "PWA Recipe" (Recommended)**
* *Pros:* Cleanest slate, allows exact configuration of `next-pwa` for offline support without fighting boilerplate defaults. Fits the "ShadCN" philosophy of "add what you need."
### Selected Starter: Standard Next.js 14+ (App Router)
**Rationale for Selection:**
We selected the **official Next.js CLI** because our architectural constraints are unique (**Local-First PWA**). Most boilerplates optimize for "SaaS B2B" (Auth+Database+Stripe), which is the opposite of our "Offline+Privacy" needs. Constructing the stack via official CLIs ensures we don't carry dead weight.
**Initialization Command:**
```bash
npx create-next-app@latest . --typescript --tailwind --eslint
# Followed by:
npx shadcn-ui@latest init
npm install next-pwa zustand dexie
```
**Architectural Decisions Provided by Starter:**
**Language & Runtime:**
- **TypeScript:** Strict mode enabled for safety.
- **Node/Runtime:** Next.js App Router (React Server Components) - *Note: We will use mostly Client Components for the PWA shell.*
**Styling Solution:**
- **Tailwind CSS:** Utility-first styling (Standard).
- **ShadCN UI:** Component architecture (Copy-paste ownership).
**Build Tooling:**
- **Turbopack:** (Next.js default) for fast HMR.
- **PostCSS:** For Tailwind compilation.
**Testing Framework:**
- *Not included by default*. We will need to add **Vitest** + **React Testing Library** in the Implementation phase.
**Code Organization:**
- **`/app` Directory:** For routing (File-system based).
- **`/components`:** Flat structure for UI elements.
- **`/lib`:** For utilities (ShadCN default).
**Development Experience:**
- **HMR:** Instant feedback.
- **ESLint:** Basic code quality.
**Note:** The specific "Offline PWA" configuration (Service Workers) will be our first major architectural implementation task.
## Core Architectural Decisions
### Data Architecture
**Database Choice:** IndexedDB (Client-Side)
- **Library Choice:** **Dexie.js v4.2.1**
- **Rationale:** Best-in-class TypeScript support and schema versioning logic (critical for PWA updates).
- **Migration Strategy:** Utilize Dexie's built-in `.version(x)` syntax to handle local DB upgrades.
### Authentication & Security
**Auth Provider:** **None (Local-First BYOD)**
- **Rationale:** No user accounts or login required. All data is local.
- **Security Pattern:** **Client-Side Key Management (Primary)**.
- **Why:** Complies with PRD "Bring Your Own AI" requirement (FR-15, FR-16). User's API key is stored in `localStorage` (with basic encoding) and sent directly to the LLM provider from the client.
- **Optional CORS Proxy:** If a provider doesn't allow browser CORS, an optional stateless Edge Function can forward requests without storing keys.
### Frontend Architecture
**Global State:** **Zustand v5**
- **Rationale:** Unopinionated and transient-update friendly (perfect for "Teacher is typing..." indicators without re-rendering the whole tree).
- **PWA Strategy:** **Custom Service Worker** (via `next-pwa`).
- **Constraint:** Must explicitly *exclude* Chat API routes from caching to prevent "stale vents."
### Infrastructure & Deployment
**Hosting:** **Vercel**
- **Rationale:** Standard Next.js hosting for app shell delivery.
- **Edge Functions:** Optional stateless CORS proxy only (not used for key management).
### Decision Impact Analysis
**Implementation Sequence:**
1. Initialize Project (Next.js + ShadCN).
2. Implement Dexie.js Schema (Data Layer).
3. Implement Zustand Store (State Layer).
4. Configure Service Worker (Offline Layer).
5. Implement Client-Side LLM Service (BYOD Integration).
6. (Optional) Setup CORS Proxy if needed for specific providers.
**Note:** The dependency chain of "Offline Sync" requires Dexie (Queue) + SW (Detection) + Zustand (UI) to all work in concert.
## Implementation Patterns & Consistency Rules
### Pattern Categories Defined
**Critical Conflict Points Identified:** 5 core areas (Naming, Structure, Format, Communication, Process).
### Naming Patterns
**Database Naming Conventions (Dexie.js):**
- **Tables:** `camelCase` (e.g., `userProfiles`, `chatLogs`). *Reason:* Matches JS object property access (`db.chatLogs.toArray()`).
- **Primary Keys:** `id` (String UUID). *Reason:* Universal, easy to generate client-side before sync.
- **Indices:** `camelCase` (e.g., `createdAt`).
**API Naming Conventions:**
- **Endpoints:** RESTful Plural Kebab-case (e.g., `/api/chat-sessions`).
- **Methods:** Standard HTTP (GET, POST, PUT, DELETE).
- **Internal Functions:** `verbNoun` (e.g., `fetchUserSession`, `syncOfflineQueue`).
### Structure Patterns
**Project Organization (Feature-First Lite):**
- **`app/`:** Routes only. Minimal logic.
- **`components/ui/`:** Primitive ShadCN components (Button, Input).
- **`components/features/{feature}/`:** Feature-specific components (e.g., `chat/ChatWindow.tsx`).
- **`lib/`:** Shared utilities (`utils.ts`) and configurations.
- **`store/`:** Zustand stores (`useChatStore.ts`).
- **`db/`:** Dexie database definition (`db.ts`).
### Format Patterns
**API Response Formats (Standardized Wrapper):**
```ts
type ApiResponse<T> = {
success: boolean;
data?: T;
error?: { code: string; message: string };
timestamp: string; // ISO 8601
}
```
### Communication Patterns
**State Management (Zustand):**
- **Selectors:** ALWAYS use atomic selectors to prevent re-renders.
- *Bad:* `const { messages, user } = useStore()`
- *Good:* `const messages = useStore((s) => s.messages)`
- **Actions:** Co-located in the store definition.
**Event System (Offline Sync):**
- **Offline Queue:** Uses robust "Action Replay" pattern.
- **Events:** `noun.verb` (e.g., `message.sent`, `session.archived`).
### Enforcement Guidelines
**All AI Agents MUST:**
1. **Strictly separate UI from Logic:** UI components must receive data via props or strict selectors; never fetch data directly inside a purely presentational component.
2. **Use the "Service Layer" for DB ops:** Never call `db.table.add()` directly in a component. Call `ChatService.sendMessage()`.
3. **Handle "Loading" vs "Syncing":** Distinguish between "fetching for the first time" (Skeleton UI) and "syncing background changes" (Subtle Spinner).
**Pattern Enforcement:**
- **Linting:** ESLint with strict import rules (e.g., no strict relative imports across features).
- **Review:** Any PR/Commit must pass the "Agent Consistency Check".
## Project Structure & Boundaries
### Complete Project Directory Structure
```text
Test01/
├── src/
│ ├── app/ # Next.js App Router (PWA Shell)
│ │ ├── (main)/ # Main Layout (Nav + content)
│ │ │ ├── page.tsx # Home/Dashboard
│ │ │ ├── history/ # Past Vents
│ │ │ └── settings/ # User Preferences
│ │ ├── (session)/ # Immersive Layout (No Nav)
│ │ │ └── chat/ # Active Venting Session
│ │ ├── api/ # API Routes (Optional CORS proxy only)
│ │ │ └── llm-proxy/ # Optional: Stateless CORS forwarder
│ │ ├── layout.tsx
│ │ └── globals.css
│ ├── components/
│ │ ├── ui/ # ShadCN Primitives (Button, Card)
│ │ ├── features/ # Feature-Specific Logic
│ │ │ ├── chat/ # ChatWindow, Bubble, TypingIndicator
│ │ │ ├── artifacts/ # ReflectionCard, SummaryView
│ │ │ └── journal/ # HistoryList, heatmaps
│ │ └── layout/ # AppShell, BottomNav, Header
│ ├── lib/
│ │ ├── db/ # Database Layer
│ │ │ ├── schema.ts # Dexie Schema Definitions
│ │ │ └── client.ts # DB Instance Singleton
│ │ ├── llm/ # AI Service Adaptation (Client-Side)
│ │ │ ├── prompt-engine.ts
│ │ │ ├── stream-parser.ts
│ │ │ └── providers.ts # Provider configurations (OpenAI, DeepSeek, etc.)
│ │ └── utils.ts # Shared Helpers
│ ├── services/ # Application Logic Layer
│ │ ├── sync-manager.ts # Offline Queue Handler
│ │ ├── llm-service.ts # Client-Side LLM Integration
│ │ └── chat-service.ts # Orchestrator (DB <-> State <-> LLM)
│ └── store/ # Global State (Zustand)
│ ├── use-session.ts # Active Session State
│ └── use-settings.ts # Theme/Config State
├── public/
│ ├── manifest.json # PWA Manifest
│ └── icons/
└── next.config.mjs # PWA + Header Config
```
### Architectural Boundaries
**Service Boundaries (The "Logic Sandwich"):**
- **UI Components** (View) -> **Zustand Store** (State) -> **Service Layer** (Logic) -> **Dexie/LLM** (Data).
- *Strict Rule:* Components NEVER import `lib/db` directly. They must use `services/`.
- *Strict Rule:* Components NEVER make `fetch()` calls directly. Use `services/llm-service.ts`.
**Data Boundaries:**
- **Local:** IndexedDB is the *Source of Truth* for User Data.
- **Remote:** LLM API is a *Compute Engine*, not a storage provider. No user data persists on the server.
- **Secrets:** API Keys are stored in `localStorage` (with simple encryption/encoding) and never leave the client except to call the provider.
### Development Workflow Integration
**Build Process:**
- `next build` generates the PWA Service Worker.
- **Edge Runtime** is optional for CORS proxy only (if needed).
**Deployment Structure:**
- **Vercel:** Hosts the App Shell (+ optional CORS proxy).
- **Client:** Browsers host the Database (IndexedDB) and execute LLM requests directly.
## Architecture Validation Results
### Coherence Validation ✅
**Decision Compatibility:**
The selected stack (**Next.js App Router** + **Dexie.js** + **Zustand**) is highly compatible. Dexie's asynchronous nature pairs well with Zustand's transient updates, ensuring the UI remains responsive even during heavy database sync operations.
**Pattern Consistency:**
Implementation patterns strongly support the "Local-First" decision. The **Service Layer** pattern is critical for isolating the UI from the complexity of Dexie/Sync logic.
### Requirements Coverage Validation ✅
**Functional Requirements Coverage:**
- **Dual-Agent Pipeline:** Supported by the `services/chat-service.ts` orchestrator logic.
- **Offline Capability:** Covered by the **Sync Queue** pattern in `services/sync-manager.ts`.
- **Privacy:** Enforced by the **Local-First** data boundary (User content stays in IndexedDB).
**Non-Functional Requirements Coverage:**
- **Performance:** **Edge Runtime** ensures <3s latency for non-cached requests.
- **Reliability:** Addressed by the "Action Replay" queue, though edge cases in sync failure need UI handling (see Gaps).
### Implementation Readiness Validation ✅
**Structure Completeness:**
The `src/` directory tree provides specific homes for every requirement. Usage of `components/features/` vs `components/ui/` is clear.
### Gap Analysis Results
**Critical Gaps:**
1. **Sync Failure UX:** Missing a defined UI pattern for "Permanent Sync Failure" (e.g., Toast with "Tap to Retry").
2. **Service Isolation:** Need explicit rule that Services return *Plain Data*, not Database Observables, to decouple UI from Dexie.
**Important Gaps:**
1. **Backoff Strategy:** `SyncManager` requires an exponential backoff policy for retries to avoid battery drain.
### Architecture Completeness Checklist
**✅ Requirements Analysis**
- [x] Project context and constraints analyzed
- [x] Cross-cutting concerns (Offline, Privacy) mapped
**✅ Architectural Decisions**
- [x] Tech Stack: Next.js + Dexie + Zustand + Auth.js
- [x] Deployment: Vercel Edge Functions
**✅ Implementation Patterns**
- [x] Structure: Feature-First Lite
- [x] State: Atomic Selectors + Service Orchestration
**✅ Project Structure**
- [x] Complete file tree defined
- [x] Integration boundaries established
### Architecture Readiness Assessment
**Overall Status:** READY FOR IMPLEMENTATION (with Gaps to address)
**Confidence Level:** HIGH
### Implementation Handoff
**First Implementation Priority:**
Initialize the **Next.js PWA Shell** and configure the **Dexie Database Schema**.
## Architecture Completion Summary
### Workflow Completion
**Architecture Decision Workflow:** COMPLETED ✅
**Total Steps Completed:** 8
**Document Location:** `_bmad-output/planning-artifacts/architecture.md`
### Final Architecture Deliverables
**📋 Complete Architecture Document**
- **Tech Stack:** Next.js 14+ (App Router), Dexie.js 4.2.1, Zustand 5, Auth.js 5.
- **Patterns:** Service Layer ("Logic Sandwich"), Client-Side Transaction Log, Local-First.
- **Structure:** Feature-First organization with clear separation of UI, State, and Logic.
### Implementation Handoff
**For AI Agents:**
This architecture document is your complete guide for implementing **Test01**. Follow all decisions, patterns, and structures exactly as documented.
**First Implementation Priority:**
Initialize the **Next.js PWA Shell** and configure the **Dexie Database Schema**.
**Development Sequence:**
1. Initialize project using Next.js CLI + ShadCN.
2. Setup Vercel Edge Proxy.
3. Implement Dexie.js Schema (Data Layer).
4. Implement Zustand Store (State Layer).
5. Configure Service Worker (Offline Layer).

19
_bmad-output/planning-artifacts/bmm-workflow-status.yaml Normal file
View File

@@ -0,0 +1,19 @@
workflow_status:
brainstorm-project: skipped
research: skipped
product-brief: /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md
prd: /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/prd.md
create-ux-design: /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
create-architecture: /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/architecture.md
create-epics-and-stories:
status: completed
file: _bmad-output/planning-artifacts/epics.md
test-design: optional
implementation-readiness: required
sprint-planning:
status: required
project_name: Test01
project_type: greenfield
project_level: 2
workflow_path: /home/maximilienmao/Projects/Test01/_bmad/bmm/workflows/workflow-status/paths/method-greenfield.yaml
last_updated: 2026-01-21

450
_bmad-output/planning-artifacts/epics.md Normal file
View File

@@ -0,0 +1,450 @@
---
stepsCompleted:
- step-01-validate-prerequisites.md
- step-02-design-epics.md
- step-03-create-stories.md
- step-04-final-validation.md
inputDocuments:
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/prd.md
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/architecture.md
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
---
# Test01 - Epic Breakdown
## Overview
This document provides the complete epic and story breakdown for Test01, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.
## Requirements Inventory
### Functional Requirements
FR-01: System can detect "Venting" vs. "Insight" intent from initial user input.
FR-02: "Teacher Agent" can generate probing questions to elicit specific missing details based on the user's initial input.
FR-03: "Ghostwriter Agent" can transform the structured interview data into a grammatically correct and structured "Enlightenment" artifact (e.g., Markdown post).
FR-04: Users can "Regenerate" the outcome with specific critique (e.g., "Make it less corporate", "Focus more on the technical solution").
FR-05: System provides a "Fast Track" option to bypass the interview and go straight to generation for advanced users.
FR-06: Users can view a chronological feed of past "Enlightenments" (history).
FR-07: Users can "One-Click Copy" the formatted text to clipboard.
FR-08: Users can delete past entries.
FR-09: Users can edit the generated draft manually before exporting.
FR-10: Users can access the app and view history while offline.
FR-11: Users can complete a full "Venting Session" offline; system queues generation for reconnection.
FR-12: System actively prompts users to "Add to Home Screen" (A2HS) upon meeting engagement criteria.
FR-13: System stores all chat history locally (persistent client-side storage) by default.
FR-14: Users can export their entire history as a JSON/Markdown file.
### NonFunctional Requirements
NFR-01 (Chat Latency): The "Teacher" agent must generate the first follow-up question within < 3 seconds to maintain conversational flow.
NFR-02 (App Load Time): The app must be interactive (Time to Interactive) in < 1.5 seconds on 4G networks.
NFR-03 (Data Sovereignty): User chat logs are stored 100% Client-Side (persistent client-side storage) in the MVP. No user content is sent to the cloud except for the temporary API inference call.
NFR-04 (Inference Privacy): Data sent to the LLM API must be stateless (not used for training).
NFR-05 (Offline Behavior): The app shell and local history must remain accessible in Aeroplane Mode. Active Chat interactions will be unavailable offline as they require live LLM access.
NFR-06 (Data Persistence): Drafts must be auto-saved locally every 2 seconds to prevent data loss.
NFR-07 (Visual Accessibility): Dark Mode is the default. Contrast ratios must meet WCAG AA standards to reduce eye strain for late-night users.
### Additional Requirements
- [Arch] Use Next.js 14+ App Router + ShadCN UI starter template
- [Arch] Implement "Local-First" architecture with Dexie.js (IndexedDB)
- [Arch] Implement Vercel Edge Functions for secure LLM API proxy
- [Arch] Use Zustand for global state management
- [Arch] Implement Service Worker for offline support and sync queue
- [UX] Implement "Morning Mist" theme with Inter (UI) and Merriweather (Content) fonts
- [UX] Implement "Chat" vs "Draft" view split pattern/slide-up sheet
- [UX] Ensure mobile-first responsive design (375px+) with centered container for desktop
- [UX] Adhere to WCAG AA accessibility standards (contrast, focus, zoom)
### FR Coverage Map
FR-01: Epic 1 - Initial intent detection logic in the main chat loop.
FR-02: Epic 1 - Teacher agent logic and prompt engineering for elicitation.
FR-03: Epic 2 - Ghostwriter agent logic and Markdown artifact generation.
FR-04: Epic 2 - Regeneration workflow for draft refinement.
FR-05: Epic 1 - Option to skip straight to generation (Fast Track).
FR-06: Epic 3 - History feed UI and data retrieval.
FR-07: Epic 2 - Copy to clipboard functionality in draft view.
FR-08: Epic 3 - Deletion management in history feed.
FR-09: Epic 2 - Manual editing capabilities for generated drafts.
FR-10: Epic 3 - Offline history access via IndexedDB.
FR-11: Epic 3 - Offline/Online sync queue for venting sessions.
FR-12: Epic 3 - PWA installation prompt logic.
FR-13: Epic 1 - Chat storage infrastructure (Dexie.js).
FR-14: Epic 3 - Data export functionality.
FR-15: Epic 4 (Story 4.1) - Custom API URL configuration.
FR-16: Epic 4 (Story 4.1) - Secure local credential storage.
FR-17: Epic 4 (Story 4.3) - Model selection logic.
FR-18: Epic 4 (Story 4.2) - Connection validation.
FR-19: Epic 4 (Story 4.4) - Provider switching logic.
## Epic List
### Epic 1: "Active Listening" - Core Chat & Teacher Agent
**Goal:** Enable users to start a session, "vent" their raw thoughts, and have the system "Active Listen" (store chat) and "Teach" (probe for details) using a local-first architecture.
**User Outcome:** Users can open the app, chat safely (locally), and get probing questions from the AI.
**FRs covered:** FR-01, FR-02, FR-05, FR-13
**NFRs:** NFR-01, NFR-03, NFR-04
### Epic 2: "The Magic Mirror" - Ghostwriter & Draft Refinement
**Goal:** Transform the structured chat context into a tangible "Enlightenment" artifact (the post) that users can review, refine, and export.
**User Outcome:** Users get a high-quality post from their vent, which they can edit and ultimately copy for publishing.
**FRs covered:** FR-03, FR-04, FR-07, FR-09
**NFRs:** NFR-07 (Visuals), NFR-04
### Epic 3: "My Legacy" - History, Offline Action Replay & PWA Polish
**Goal:** Turn single sessions into a persistent "Journal" of growth, ensuring the app works flawlessly offline and behaves like a native app.
**User Outcome:** Users can view past wins, use the app on the subway (offline), and install it to their home screen.
**FRs covered:** FR-06, FR-08, FR-10, FR-11, FR-12, FR-14
**NFRs:** NFR-02, NFR-05, NFR-06
### Epic 4: "Power User Settings" - BYOD & Configuration
**Goal:** Enable users to bring their own Intelligence (BYOD) by configuring custom API providers, models, and keys, satisfying the "Privacy-First" and "Vendor Independence" requirements.
**User Outcome:** Users can configure and switch between different AI providers with their own API keys, ensuring data privacy and vendor flexibility.
**FRs covered:** FR-15, FR-16, FR-17, FR-18, FR-19
**NFRs:** NFR-03 (Data Sovereignty), NFR-08 (Secure Key Storage)
## Epic 1: "Active Listening" - Core Chat & Teacher Agent
**Goal:** Enable users to start a session, "vent" their raw thoughts, and have the system "Active Listen" (store chat) and "Teach" (probe for details) using a local-first architecture.
### Story 1.1: Local-First Setup & Chat Storage
As a user,
I want my chat sessions to be saved locally on my device,
So that my data is private and accessible offline.
**Acceptance Criteria:**
**Given** a new user visits the app
**When** they load the page
**Then** a Dexie.js database is initialized with the correct schema
**And** no data is sent to the server without explicit action
**Given** the user sends a message
**When** the message is sent
**Then** it is stored in the `chatLogs` table in IndexedDB with a timestamp
**And** is immediately displayed in the UI
**Given** the user reloads the page
**When** the page loads
**Then** the previous chat history is retrieved from IndexedDB and displayed correctly
**And** the session state is restored
**Given** the device is offline
**When** the user opens the app
**Then** the app loads successfully and shows stored history from the local database
### Story 1.2: Chat Interface Implementation
As a user,
I want a clean, familiar chat interface,
So that I can focus on venting without fighting the UI.
**Acceptance Criteria:**
**Given** a user is on the main chat screen
**When** they look at the UI
**Then** they see a "Morning Mist" themed interface with distinct bubbles for User (Right) and AI (Left)
**And** the design matches the "Telegram-style" visual specification
**Given** the user is typing
**When** they press "Send"
**Then** the input field clears and the message appears in the chat
**And** the view scrolls to the bottom
**Given** the user is on a mobile device
**When** they view the chat
**Then** the layout is responsive and all touch targets are at least 44px
**And** the text size is legible (Inter font)
**Given** the AI is processing
**When** the user waits
**Then** a "Teacher is typing..." indicator is visible
**And** the UI remains responsive
### Story 1.3: Teacher Agent Logic & Intent Detection
As a user,
I want the AI to understand if I'm venting or sharing an insight,
So that it responds appropriately.
**Acceptance Criteria:**
**Given** a user sends a first message
**When** the AI processes it
**Then** it classifies the intent as "Venting" or "Insight"
**And** stores this context in the session state
**Given** the intent is "Venting"
**When** the AI responds
**Then** it validates the emotion first
**And** asks a probing question to uncover the underlying lesson
**Given** the AI is generating a response
**When** the request is sent
**Then** it makes a direct client-side request to the configured Provider
**And** the user's stored API key is retrieved from local secure storage
**Given** the API response takes time
**When** the user waits
**Then** the response time is optimized to be under 3 seconds for the first token (if streaming)
### Story 1.4: Fast Track Mode
As a Power User,
I want to bypass the interview questions,
So that I can generate a post immediately if I already have the insight.
**Acceptance Criteria:**
**Given** a user is in the chat
**When** they toggle "Fast Track" or press a specific "Just Draft It" button
**Then** the AI skips the probing phase
**And** proceeds directly to the "Ghostwriter" generation phase (transition to Epic 2 workflow)
**Given** "Fast Track" is active
**When** the user sends their input
**Then** the system interprets it as the final insight
**And** immediately triggers the draft generation
## Epic 2: "The Magic Mirror" - Ghostwriter & Draft Refinement
**Goal:** Transform the structured chat context into a tangible "Enlightenment" artifact (the post) that users can review, refine, and export.
### Story 2.1: Ghostwriter Agent & Markdown Generation
As a user,
I want the system to draft a polished post based on my chat,
So that I can see my raw thoughts transformed into value.
**Acceptance Criteria:**
**Given** the user has completed the interview or used "Fast Track"
**When** the "Ghostwriter" agent is triggered
**Then** it consumes the entire chat history and the "Lesson" context
**And** generates a structured Markdown artifact (Title, Body, Tags)
**Given** the generation is processing
**When** the user waits
**Then** they see a distinct "Drafting" animation (different from "Typing")
**And** the tone of the output matches the "Professional/LinkedIn" persona
### Story 2.2: Draft View UI (The Slide-Up)
As a user,
I want to view the generated draft in a clean, reading-focused interface,
So that I can review it without the distraction of the chat.
**Acceptance Criteria:**
**Given** the draft generation is complete
**When** the result is ready
**Then** a "Sheet" or modal slides up from the bottom
**And** it displays the post in "Medium-style" typography (Merriweather font)
**Given** the draft view is open
**When** the user scrolls
**Then** the reading experience is comfortable with appropriate whitespace
**And** the "Thumbs Up" and "Thumbs Down" actions are sticky or easily accessible
### Story 2.3: Refinement Loop (Regeneration)
As a user,
I want to provide feedback if the draft isn't right,
So that I can get a better version.
**Acceptance Criteria:**
**Given** the user is viewing a draft
**When** they click "Thumbs Down"
**Then** the draft sheet closes and returns to the Chat UI
**And** the AI proactively asks "What should we change?"
**Given** the user provides specific critique (e.g., "Make it shorter")
**When** they send the feedback
**Then** the "Ghostwriter" regenerates the draft respecting the new constraint
**And** the new draft replaces the old one in the Draft View
### Story 2.4: Export & Copy Actions
As a user,
I want to copy the text or save the post,
So that I can publish it on LinkedIn or save it for later.
**Acceptance Criteria:**
**Given** the user likes the draft
**When** they click "Thumbs Up" or "Copy"
**Then** the full Markdown text is copied to the clipboard
**And** a success toast/animation confirms the action
**Given** the draft is finalized
**When** the user saves it
**Then** it is marked as "Completed" in the local database
**And** the user is returned to the Home/History screen
## Epic 3: "My Legacy" - History, Offline Sync & PWA Polish
**Goal:** Turn single sessions into a persistent "Journal" of growth, ensuring the app works flawlessly offline and behaves like a native app.
### Story 3.1: History Feed UI
As a user,
I want to see a list of my past growing moments,
So that I can reflect on my journey.
**Acceptance Criteria:**
**Given** the user is on the Home screen
**When** they view the feed
**Then** they see a chronological list of past "Completed" sessions (Title, Date, Tags)
**And** the list supports lazy loading/pagination for performance
**Given** the user clicks a history card
**When** the card opens
**Then** the full "Enlightenment" artifact allows for reading
**And** the "Copy" action is available
### Story 3.2: Deletion & Management
As a user,
I want to delete old entries,
So that I can control my private data.
**Acceptance Criteria:**
**Given** the user is viewing a past entry
**When** they select "Delete"
**Then** they are prompted with a confirmation dialog (Destructive Action)
**And** the action cannot be undone
**Given** the deletion is confirmed
**When** the action completes
**Then** the entry is permanently removed from IndexedDB
**And** the History Feed updates immediately to remove the item
### Story 3.3: Offline Action Replay
As a user,
I want my actions to be queued when offline,
So that I don't lose work on the subway.
**Acceptance Criteria:**
**Given** the device is offline
**When** the user performs an LLM-dependent action (e.g., Send message, Regenerate draft)
**Then** the action is added to a persistent "Action Queue" in Dexie
**And** the UI shows a subtle "Offline - Queued" indicator
**Given** connection is restored
**When** the app detects the network
**Then** the Sync Manager replays queued actions to the LLM API
**And** the indicator updates to "Processed"
### Story 3.4: PWA Install Prompt & Manifest
As a user,
I want to install the app to my home screen,
So that it feels like a native app.
**Acceptance Criteria:**
**Given** the user visits the web app
**When** the browser parses the site
**Then** it finds a valid `manifest.json` with correct icons, name ("Test01"), and `display: standalone` settings
**Given** the user has engaged with the app (e.g., completed 1 session)
**When** the browser supports it (beforeinstallprompt event)
**Then** a custom "Install App" UI element appears (non-intrusive)
**And** clicking it triggers the native install prompt
**Given** the app is installed
**When** it launches from Home Screen
**Then** it opens without the browser URL bar (Standalone mode)
## Epic 4: "Power User Settings" - BYOD & Configuration
**Goal:** Enable users to bring their own Intelligence (BYOD) by configuring custom API providers, models, and keys, satisfying the "Privacy-First" and "Vendor Independence" requirements.
### Story 4.1: API Provider Configuration UI
As a user,
I want to enter my own API Key and Base URL,
So that I can use my own LLM account (e.g., DeepSeek, OpenAI).
**Acceptance Criteria:**
**Given** the user navigates to "Settings"
**When** they select "AI Provider"
**Then** they see a form to enter: "Base URL" (Default: OpenAI), "API Key", and "Model Name"
**Given** the user enters a key
**When** they save
**Then** the key is stored in `localStorage` with basic encoding (not plain text)
**And** it is NEVER sent to the app backend (Client-Side only)
**Given** the user has saved a provider
**When** they return to chat
**Then** the new settings are active immediately
### Story 4.2: Connection Validation
As a user,
I want to know if my key works,
So that I don't get errors in the middle of a chat.
**Acceptance Criteria:**
**Given** the user enters new credentials
**When** they click "Connect" or "Save"
**Then** the system sends a tiny "Hello" request to the provider
**And** shows "Connected ✅" if successful, or the error message if failed
### Story 4.3: Model Selection & Configuration
As a user,
I want to specify which AI model to use,
So that I can choose between different capabilities (e.g., fast vs. smart).
**Acceptance Criteria:**
**Given** the user is in the API Provider settings
**When** they view the form
**Then** they see a "Model Name" field with examples (e.g., "gpt-4o", "deepseek-chat")
**Given** the user enters a custom model name
**When** they save
**Then** the model name is stored alongside the API key and base URL
**And** all future LLM requests use this model identifier
**Given** the user doesn't specify a model
**When** they save provider settings
**Then** a sensible default is used (e.g., "gpt-3.5-turbo" for OpenAI endpoints)
### Story 4.4: Provider Switching
As a user,
I want to switch between different saved providers,
So that I can use different AI services for different needs.
**Acceptance Criteria:**
**Given** the user has configured multiple providers
**When** they open Settings
**Then** they see a list of saved providers with labels (e.g., "OpenAI GPT-4", "DeepSeek Chat")
**Given** the user selects a different provider
**When** they confirm the switch
**Then** the app immediately uses the new provider for all LLM requests
**And** the active provider is persisted in local storage
**Given** the user starts a new chat session
**When** they send messages
**Then** the currently active provider is used
**And** the provider selection is maintained across page reloads

190
_bmad-output/planning-artifacts/implementation-readiness-report-2026-01-21.md Normal file
View File

@@ -0,0 +1,190 @@
---
stepsCompleted:
- step-01-document-discovery.md
- step-02-prd-analysis.md
- step-03-epic-coverage-validation.md
- step-04-ux-alignment.md
- step-05-epic-quality-review.md
- step-06-final-assessment.md
files:
prd: /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/prd.md
architecture: /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/architecture.md
epics: /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/epics.md
ux: /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
---
# Implementation Readiness Assessment Report
**Date:** 2026-01-21
**Project:** Test01
## PRD Analysis
### Functional Requirements
**Dual-Agent Pipeline (Core Innovation)**
* **FR-01:** System can detect "Venting" vs. "Insight" intent from initial user input.
* **FR-02:** "Teacher Agent" can generate probing questions to elicit specific missing details based on the user's initial input.
* **FR-03:** "Ghostwriter Agent" can transform the structured interview data into a grammatically correct and structured "Enlightenment" artifact (e.g., Markdown post).
* **FR-04:** Users can "Regenerate" the outcome with specific critique (e.g., "Make it less corporate", "Focus more on the technical solution").
* **FR-05:** System provides a "Fast Track" option to bypass the interview and go straight to generation for advanced users.
**Content Management**
* **FR-06:** Users can view a chronological feed of past "Enlightenments" (history).
* **FR-07:** Users can "One-Click Copy" the formatted text to clipboard.
* **FR-08:** Users can delete past entries.
* **FR-09:** Users can edit the generated draft manually before exporting.
**PWA & Offline Capabilities**
* **FR-10:** Users can access the app and view history while offline.
* **FR-11:** Users can complete a full "Venting Session" offline; system queues generation for reconnection.
* **FR-12:** System actively prompts users to "Add to Home Screen" (A2HS) upon meeting engagement criteria.
**Data & Privacy**
* **FR-13:** System stores all chat history locally (persistent client-side storage) by default.
* **FR-14:** Users can export their entire history as a JSON/Markdown file.
Total FRs: 14
### Non-Functional Requirements
**Performance & Responsiveness**
* **NFR-01 (Chat Latency):** The "Teacher" agent must generate the first follow-up question within **< 3 seconds** to maintain conversational flow.
* **NFR-02 (App Load Time):** The app must be interactive (Time to Interactive) in **< 1.5 seconds** on 4G networks.
**Privacy & Security**
* **NFR-03 (Data Sovereignty):** User chat logs are stored **100% Client-Side** (persistent client-side storage) in the MVP. No user content is sent to the cloud except for the temporary API inference call.
* **NFR-04 (Inference Privacy):** Data sent to the LLM API must be stateless (not used for training).
**Reliability & Offline**
* **NFR-05 (Offline Behavior):** The app shell and local history must remain accessible in Aeroplane Mode. **Note:** Active Chat interactions will be unavailable offline as they require live LLM access.
* **NFR-06 (Data Persistence):** Drafts must be auto-saved locally every **2 seconds** to prevent data loss.
**Accessibility**
* **NFR-07 (Visual Accessibility):** Dark Mode is the default. Contrast ratios must meet **WCAG AA** standards to reduce eye strain for late-night users.
Total NFRs: 7
### Additional Requirements
**Domain-Specific Requirements**
* **Data Privacy (Adult Learners):** Strict control over private "Venting" logs.
* **Content Moderation:** Guardrails to prevent generating toxic/offensive content.
* **Tone Safety:** "Professional yet Authentic" tone.
* **Hallucination Prevention:** Strict prompt engineering grounded in user input.
* **Bloom's Taxonomy Application:** Scaffolding from Remembering -> Understanding -> Creating.
**PWA Technical Constraints**
* **Installability:** Valid `manifest.json`.
* **Browser Support:** Tier 1 (iOS Safari, Android Chrome).
* **SEO Strategy:** Public marketing page indexed; private app routes `noindex`.
### PRD Completeness Assessment
The PRD is highly detailed and structurally sound. Requirements are specific, measurable (where applicable), and traceable to user journeys. The core innovation (Dual-Agent) is clearly defined in FRs. NFRs cover critical PWA aspects like offline behavior and privacy. The scope is well-bounded for an MVP.
## Epic Coverage Validation
### Coverage Matrix
| FR Number | PRD Requirement | Epic Coverage | Status |
| :-------- | :----------------------------------- | :------------------------------- | :-------- |
| **FR-01** | Detect "Venting" vs "Insight" intent | Epic 1: Core "Venting to Wisdom" | ✅ Covered |
| **FR-02** | Teacher probing questions | Epic 1: Core "Venting to Wisdom" | ✅ Covered |
| **FR-03** | Ghostwriter drafting | Epic 1: Core "Venting to Wisdom" | ✅ Covered |
| **FR-04** | Regenerate with critique | Epic 1: Core "Venting to Wisdom" | ✅ Covered |
| **FR-05** | Fast Track option | Epic 4: Advanced Workflow | ✅ Covered |
| **FR-06** | History feed | Epic 2: Content Management | ✅ Covered |
| **FR-07** | One-Click Copy | Epic 1: Core "Venting to Wisdom" | ✅ Covered |
| **FR-08** | Delete entries | Epic 2: Content Management | ✅ Covered |
| **FR-09** | Manual draft editing | Epic 2: Content Management | ✅ Covered |
| **FR-10** | Offline access | Epic 3: Offline Capability | ✅ Covered |
| **FR-11** | Offline venting session | Epic 3: Offline Capability | ✅ Covered |
| **FR-12** | Add to Home Screen prompts | Epic 3: Offline Capability | ✅ Covered |
| **FR-13** | Local storage (client-side) | Epic 1: Core "Venting to Wisdom" | ✅ Covered |
| **FR-14** | Export history | Epic 2: Content Management | ✅ Covered |
### Missing Requirements
* **None.** All Functional Requirements are explicitly mapped to Epics and Stories.
### Coverage Statistics
* **Total PRD FRs:** 14
* **FRs covered in epics:** 14
* **Coverage percentage:** 100%
## UX Alignment Assessment
### UX Document Status
**Found:** `ux-design-specification.md`
### Alignment Analysis
The UX Specification is fully aligned with both the PRD and Reference Architecture.
**UX ↔ PRD Alignment**
* **Core Loop:** The "Venting -> Insight" journey in the PRD is perfectly visualized in the UX "Daily Vent" flow.
* **Dual-Agent Interaction:** The UX explicitly designs for "Teacher" (Chat Bubble) and "Ghostwriter" (Draft Card) distinct visual modes, supporting PRD FR-01/02/03.
* **PWA Features:** PRD FR-10/12 (Offline/A2HS) are central to the UX "Platform Strategy" and "Responsive Design" sections.
**UX ↔ Architecture Alignment**
* **Tech Stack:** Both documents specify **ShadCN UI** + **Tailwind** + **Next.js**.
* **State Management:** UX "Slide-Up" sheets are supported by the Architecture's decision to use **Zustand** for transient UI state.
* **Offline Data:** UX requirement for "local retention" is backed by the **Dexie.js** decision in Architecture.
* **Visual System:** The "Morning Mist" theme is acknowledged as a cross-cutting concern in Architecture.
### Alignment Issues
* **None.** The documentation set is highly coherent.
### Warnings
* **None.**
## Epic Quality Review
### Structure Validation
* **User Value Focus:** ✅ **PASS**. All 4 Epics focus on User Outcomes ("Venting", "Legacy Log", "Access Anywhere", "Streamlined Flow"). No pure "Technical Epics" found.
* **Epic Independence:** ✅ **PASS**. Epic 1 provides the core end-to-end value independently. Epic 2 and 3 add value on top without creating circular dependencies.
* **Greenfield Compliance:** ✅ **PASS**. Epic 1 Story 1 ("Project Initialization") correctly follows the Greenfield project requirement to set up the foundation first.
### Story Quality Assessment
* **Sizing:** Stories are well-sliced (e.g., separating "Teacher Logic" from "Ghostwriter Logic" ensures clear scope).
* **Acceptance Criteria:** All stories use strict **Given/When/Then** BDD format with clear success states.
* **Dependencies:** Stories follow a logical linear progression (Init -> Basic Chat -> Agents -> Refinement).
### Violations Finding
* **Critical Violations:** None.
* **Major Issues:** None.
* **Minor Concerns:** None.
### Recommendations
* **Strategy:** The planned Epic breakdown is **Ready for Implementation**.
* **Testing:** Ensure Story 3.2 ("Action Replay Queue") is tested under actual offline conditions (Airplane Mode) as per AC.
## Summary and Recommendations
### Overall Readiness Status
# ✅ READY FOR IMPLEMENTATION
The project documentation (PRD, Architecture, UX, Epics) is complete, coherent, and highly traceable. The "Greenfield" MVP scope is well-defined and structurally sound.
### Critical Issues Requiring Immediate Action
* **None.** Zero critical blocking issues were identified across 4 validation passes.
### Recommended Next Steps
1. **Sprint Planning:** Move to Phase 4 and load Epics into the sprint tracker.
2. **Initialize Project:** Execute Epic 1 / Story 1.1 to scaffold the Next.js PWA.
3. **Setup Edge Proxy:** Prioritize the security layer (Story 1.1) before building features.
### Final Note
This assessment identified **0** critical issues across **4** categories (Requirements, UX, Architecture, Epics). The project is in an optimal state to begin coding.

196
_bmad-output/planning-artifacts/implementation-readiness-report-2026-01-23.md Normal file
View File

@@ -0,0 +1,196 @@
# Implementation Readiness Assessment Report
**Date:** 2026-01-23
**Project:** Test01
## 1. Document Inventory
**Status:** ✅ Complete
**Verified Documents:**
- **PRD:** `prd.md`
- **Architecture:** `architecture.md`
- **Epics:** `epics.md`
- **UX Design:** `ux-design-specification.md`
All required documents are present and accounted for.
## 2. PRD Analysis
### Functional Requirements
**Dual-Agent Pipeline**
- **FR-01:** System can detect "Venting" vs. "Insight" intent from initial user input.
- **FR-02:** "Teacher Agent" can generate probing questions to elicit specific missing details based on the user's initial input.
- **FR-03:** "Ghostwriter Agent" can transform the structured interview data into a grammatically correct and structured "Enlightenment" artifact.
- **FR-04:** Users can "Regenerate" the outcome with specific critique.
- **FR-05:** System provides a "Fast Track" option to bypass the interview and go straight to generation.
**Content Management**
- **FR-06:** Users can view a chronological feed of past "Enlightenments" (history).
- **FR-07:** Users can "One-Click Copy" the formatted text to clipboard.
- **FR-08:** Users can delete past entries.
- **FR-09:** Users can edit the generated draft manually before exporting.
**PWA & Offline Capabilities**
- **FR-10:** Users can access the app and view history while offline.
- **FR-11:** Users can complete a full "Venting Session" offline; system queues generation for reconnection.
- **FR-12:** System actively prompts users to "Add to Home Screen" (A2HS).
**Data & Privacy**
- **FR-13:** System stores all chat history locally (persistent client-side storage) by default.
- **FR-14:** Users can export their entire history as a JSON/Markdown file.
**AI Configuration & Settings (BYOD)**
- **FR-15:** Users can configure a custom OpenAI-compatible Base URL.
- **FR-16:** Users can securely save API Credentials (stored in local storage, never transmitted to backend).
- **FR-17:** Users can specify the Model Name.
- **FR-18:** System validates the connection to the custom provider upon saving.
- **FR-19:** Users can switch between configured providers globally.
**Total FRs:** 19
### Non-Functional Requirements
**Performance & Responsiveness**
- **NFR-01 (Chat Latency):** "Teacher" agent must generate first follow-up question within **< 3 seconds**.
- **NFR-02 (App Load Time):** App must be interactive in **< 1.5 seconds** on 4G networks.
**Privacy & Security**
- **NFR-03 (Data Sovereignty):** User chat logs AND API Keys are stored **100% Client-Side**.
- **NFR-04 (Inference Privacy):** Data sent to LLM API must be stateless.
- **NFR-08 (Secure Key Storage):** API Keys must be encrypted at rest or stored in secure local storage capabilities.
**Reliability & Offline**
- **NFR-05 (Offline Behavior):** App shell and local history accessible in Aeroplane Mode.
- **NFR-06 (Data Persistence):** Drafts auto-saved locally every **2 seconds**.
**Accessibility**
- **NFR-07 (Visual Accessibility):** Dark Mode is default. Contrast ratios must meet **WCAG AA** standards.
**Total NFRs:** 8
### Additional Requirements & Constraints
- **Compliance:** Data Privacy for Adult Learners, Content Moderation.
- **Tone Safety:** Professional tone.
- **Hallucination Prevention:** Strict prompt engineering.
- **Accessibility:** WCAG 2.1 AA.
- **PWA Constraints:** Offline mode, Service Workers.
- **Responsive Design:** Mobile-first, desktop center container.
- **SEO:** Public marketing page SEO.
### PRD Completeness Assessment
The PRD is very detailed and structured. Requirements are explicitly numbered.
**Assessment:** ✅ High Completeness.
## 3. Epic Coverage Validation
### Coverage Matrix
| FR Number | PRD Requirement | Epic Coverage | Status |
| :-------- | :------------------- | :------------ | :-------- |
| FR-01 | Intent Detection | Epic 1 | ✅ Covered |
| FR-02 | Teacher Agent Logic | Epic 1 | ✅ Covered |
| FR-03 | Ghostwriter Logic | Epic 2 | ✅ Covered |
| FR-04 | Regeneration | Epic 2 | ✅ Covered |
| FR-05 | Fast Track | Epic 1 | ✅ Covered |
| FR-06 | History Feed | Epic 3 | ✅ Covered |
| FR-07 | Copy to Clipboard | Epic 2 | ✅ Covered |
| FR-08 | Delete Entries | Epic 3 | ✅ Covered |
| FR-09 | Manual Edit | Epic 2 | ✅ Covered |
| FR-10 | Offline Access | Epic 3 | ✅ Covered |
| FR-11 | Offline Sync | Epic 3 | ✅ Covered |
| FR-12 | PWA Install | Epic 3 | ✅ Covered |
| FR-13 | Local Storage | Epic 1 | ✅ Covered |
| FR-14 | Data Export | Epic 3 | ✅ Covered |
| FR-15 | Custom API URL | **NOT FOUND** | ❌ MISSING |
| FR-16 | Save API Credentials | **NOT FOUND** | ❌ MISSING |
| FR-17 | Specify Model Name | **NOT FOUND** | ❌ MISSING |
| FR-18 | Validate Connection | **NOT FOUND** | ❌ MISSING |
| FR-19 | Switch Providers | **NOT FOUND** | ❌ MISSING |
### Missing Requirements
5 Functional Requirements are missing from the Epics document. These relate to the recently added "Bring Your Own AI" (BYOD) capabilities in the PRD (added 2026-01-23).
#### Critical Missing FRs
- **FR-15:** Users can configure a custom OpenAI-compatible Base URL.
- **FR-16:** Users can securely save API Credentials (stored in local storage, never transmitted to backend).
- **FR-17:** Users can specify the Model Name (e.g., `gpt-4o`, `deepseek-chat`).
- **FR-18:** System validates the connection to the custom provider upon saving.
- **FR-19:** Users can switch between configured providers globally.
**Impact:** The core "Technical Differentiator" of BYOD Architecture is largely unimplemented in the Epics. This is a critical gap for the MVP if BYOD is a Phase 1 requirement.
**Recommendation:** Create a new **Epic 4: "Power User Settings"** or add stories to Epic 3 to handle AI Configuration, Secure Storage of Keys, and Provider switching.
### Coverage Statistics
- Total PRD FRs: 19
- FRs covered in epics: 14
- Coverage percentage: 73.6%
## 4. UX Alignment Assessment
### UX Document Status
✅ **Found** (`ux-design-specification.md`)
### Alignment Issues
#### ⚠️ Critical Architecture Conflict (BYOD vs. Proxy)
- **PRD Alignment:** The PRD (updated 2026-01-23) specifically requires a **"Bring Your Own AI" (BYOD)** model where "Users provide their own API keys... No middle-man server" (FR-15, FR-16, NFR-03).
- **Architecture Conflict:** The `architecture.md` (dated 2026-01-21) specifies a "Vercel Edge Functions as API Proxy" pattern to "Hide LLM API keys from the client" (SaaS model).
- **Impact:** The approved architecture effectively blocks the implementation of the BYOD requirement. A middle-man proxy contradicts NFR-03 ("No user content or keys are sent to any middle-man server").
#### ⚠️ Missing UX Flows (BYOD)
- **Gap:** The UX Specification does not contain screens or flows for the "Settings" or "API Configuration" screens required by FR-15 to FR-19.
- **Impact:** Developers will have no design guidance for this complex configuration flow.
### Warnings
- **Architecture is outdated:** It reflects the project state before the "BYOD" requirement.
- **UX is outdated:** It lacks the Power User configuration journeys.
## 5. Epic Quality Review
### Structure & Sizing
- **Structure:** Epics are user-focused and value-driven.
- **Sizing:** Stories are adequately sized for individual completion.
- **Dependencies:** Logical progression from Core (Epic 1) -> Feature (Epic 2) -> Reliability (Epic 3).
### Violations & Concerns
#### 🔴 Critical Violations
1. **Story 1.3 Implementation Conflict:** Story 1.3 AC states "Then it goes through a Vercel Edge Function proxy... API keys are not exposed to the client." This explicitly implements the **SaaS Proxy pattern**, which directly contradicts the **BYOD requirement** (FR-15) and NFR-03. Implementing this story as written will result in a defective product that fails 5 Functional Requirements.
2. **Missing Configuration Stories:** There are no stories for "Settings", "Configuration", or "API Key Management", leaving the BYOD requirement completely unplanned.
#### 🟠 Major Issues
1. **Ambiguous "Sync" (Story 3.3):** The term "Sync" in Story 3.3 ("Offline Sync Queue") is ambiguous. Given NFR-03 ("No user content sent to cloud"), "Sync" likely refers to "Replaying actions to the LLM API" for generation. However, the AC "indicator updates to 'Synced'" implies data synchronization. This needs clarification to avoid developers building a cloud sync engine unnecessarily.
### Recommendations
1. **Refactor Epic 1:** Rewrite Story 1.3 to support Client-Side API calls (or stateless proxy with user-provided keys) to align with BYOD.
2. **Create Epic 4:** Define "Settings & Configuration" Epic to handle all BYOD Logic (Input keys, Validate, Save to LocalStorage).
3. **Clarify Story 3.3:** Rename to "Offline Action Replay" and clarify the ACs to refer to "Processing Pending Generations" rather than "Syncing".
## 6. Summary and Recommendations
### Overall Readiness Status
🚫 **NEEDS WORK** (Assessment: NOT READY for Implementation)
### Critical Issues Requiring Immediate Action
1. **Resolve BYOD vs. SaaS Architecture Conflict:** The Architecture and Stories (1.3) are designed for a centralised SaaS app with a hidden API key, but the PRD demands a strict "Bring Your Own AI" / Client-Side privacy model. This is a fundamental blocker.
2. **Fill Coverage Gaps:** 5 FRs related to AI Provider Configuration (FR-15 to FR-19) are missing from Epics and UX.
3. **Ambiguity in Sync Requirements:** Developers may waste time building unnecessary cloud sync infrastructure if Story 3.3 is not clarified.
### Recommended Next Steps
1. **Update Architecture:** Modify `architecture.md` to support "Input Key + Client-Side Calls" pattern or "Stateless Gateway". Remove the mandatory "Proxy to hide keys" requirement.
2. **Update UX:** Create a "Settings" page mock for API Key entry and Model selection.
3. **Create Epic 4:** "Power User Settings" to implement the `Settings -> API Provider` user journey.
4. **Refactor Story 1.3:** Remove the "hidden proxy" AC and replace with "uses configured provider".
### Final Note
This assessment identified **3 Critical Conflicts** and **5 Missing Requirements**. The project is **NOT READY** for implementation until the BYOD Architecture conflict is resolved. Developing Epic 1 as effectively specified would create technical debt that would be immediately discarded.

305
_bmad-output/planning-artifacts/prd-validation-report-2026-01-21.md Normal file
View File

@@ -0,0 +1,305 @@
---
validationTarget: '/home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/prd.md'
validationDate: '2026-01-21'
inputDocuments:
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux_brainstorm_notes.md
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
- file:///home/maximilienmao/Projects/Test01/_bmad-output/analysis/brainstorming-session-2026-01-20.md
validationStepsCompleted: ['step-v-01-discovery', 'step-v-02-format-detection', 'step-v-03-density-validation', 'step-v-04-brief-coverage-validation', 'step-v-05-measurability-validation', 'step-v-06-traceability-validation', 'step-v-07-implementation-leakage-validation', 'step-v-08-domain-compliance-validation', 'step-v-09-project-type-validation', 'step-v-10-smart-validation', 'step-v-11-holistic-quality-validation', 'step-v-12-completeness-validation']
validationStatus: COMPLETE
holisticQualityRating: '5/5'
overallStatus: 'Pass'
---
# PRD Validation Report (Post-Edit Verification)
**PRD Being Validated:** /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/prd.md
**Validation Date:** 2026-01-21
## Input Documents
- `product-brief-Test01-2026-01-20.md`
- `ux_brainstorm_notes.md`
- `ux-design-specification.md`
- `brainstorming-session-2026-01-20.md`
## Validation Findings
[Findings will be appended as validation progresses]
### Format Detection
**PRD Structure:**
- Executive Summary
- Success Criteria
- Product Scope
- User Journeys
- Domain-Specific Requirements
- Innovation & Novel Patterns
- Web App Specific Requirements
- Project Scoping & Phased Development
- Functional Requirements
- Non-Functional Requirements
**BMAD Core Sections Present:**
- Executive Summary: Present
- Success Criteria: Present
- Product Scope: Present
- User Journeys: Present
- Functional Requirements: Present
- Non-Functional Requirements: Present
**Format Classification:** BMAD Standard
**Core Sections Present:** 6/6
### Information Density Validation
**Anti-Pattern Violations:**
**Conversational Filler:** 0 occurrences
**Wordy Phrases:** 0 occurrences
**Redundant Phrases:** 0 occurrences
**Total Violations:** 0
**Severity Assessment:** Pass
**Recommendation:**
PRD demonstrates good information density with minimal violations.
## Product Brief Coverage
**Product Brief:** product-brief-Test01-2026-01-20.md
**Coverage Map:**
- **Vision Statement:** Fully Covered
- **Target Users:** Fully Covered
- **Problem Statement:** Fully Covered
- **Key Features:** Fully Covered
- **Goals/Objectives:** Fully Covered
- **Differentiators:** Fully Covered
**Coverage Summary:**
- **Overall Coverage:** 100%
- **Critical Gaps:** 0
- **Moderate Gaps:** 0
- **Informational Gaps:** 0
**Recommendation:**
PRD provides excellent coverage of the Product Brief content.
## Measurability Validation
### Functional Requirements
**Format Violations:** 0
**Subjective Adjectives Found:** 0
**Vague Quantifiers Found:** 0
**Implementation Leakage:** 0
**FR Violations Total:** 0
### Non-Functional Requirements
**Missing Metrics:** 0
**Incomplete Template:** 0
**Missing Context:** 0
**NFR Violations Total:** 0
### Overall Assessment
**Total Requirements:** 18 (14 FR + 4 NFR)
**Total Violations:** 0
**Severity:** Pass
**Recommendation:** Requirements demonstrate excellent measurability.
## Traceability Validation
### Chain Validation
**Executive Summary → Success Criteria:** Intact
**Success Criteria → User Journeys:** Intact
**User Journeys → Functional Requirements:** Intact
**Scope → FR Alignment:** Intact
### Orphan Elements
**Orphan Functional Requirements:** 0
**Unsupported Success Criteria:** 0
**User Journeys Without FRs:** 0
### Traceability Matrix
All FRs trace back to defined User Journeys or NFRs.
**Total Traceability Issues:** 0
**Severity:** Pass
**Recommendation:** Traceability chain is intact.
## Implementation Leakage Validation
### Leakage by Category
**Frontend Frameworks:** 0
**Backend Frameworks:** 0
**Databases:** 0
**Cloud Platforms:** 0
**Infrastructure:** 0
**Libraries:** 0
**Other Implementation Details:** 0
### Summary
**Total Implementation Leakage Violations:** 0
**Severity:** Pass
**Recommendation:** No significant implementation leakage found.
## Domain Compliance Validation
**Domain:** edtech
**Complexity:** High (regulated)
### Required Special Sections
**Compliance & Regulatory:** Present
**Educational Framework Alignment:** Present
**Accessibility:** Present
### Compliance Matrix
| Requirement | Status | Notes |
| ----------------------------- | ------ | ---------------------------------------- |
| Data Privacy (Adult Learners) | Met | Detailed in Domain-Specific Requirements |
| Content Moderation | Met | Addressed for reputation safety |
| Educational Framework | Met | Bloom's Taxonomy alignment added |
| Accessibility | Met | WCAG 2.1 AA specified |
### Summary
**Required Sections Present:** 3/3
**Compliance Gaps:** 0
**Severity:** Pass
**Recommendation:** All required domain compliance sections are present and adequately documented.
## Project-Type Compliance Validation
**Project Type:** web_app
### Required Sections
**User Journeys:** Present
**UX/UI Requirements:** Present (Web App Specific Requirements)
**Responsive Design:** Present
### Excluded Sections (Should Not Be Present)
**None:** 0 violations
### Compliance Summary
**Required Sections:** 3/3 present
**Excluded Sections Present:** 0
**Compliance Score:** 100%
**Severity:** Pass
**Recommendation:** All required web_app sections are present.
## SMART Requirements Validation
**Total Functional Requirements:** 14
### Scoring Summary
**All scores ≥ 3:** 100% (14/14)
**All scores ≥ 4:** 100% (14/14)
**Overall Average Score:** 5.0/5.0
### Scoring Table
| FR # | Specific | Measurable | Attainable | Relevant | Traceable | Average | Flag |
| ----- | -------- | ---------- | ---------- | -------- | --------- | ------- | ---- |
| FR-01 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-02 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-03 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-04 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-05 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-06 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-07 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-08 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-09 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-10 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-11 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-12 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-13 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
| FR-14 | 5 | 5 | 5 | 5 | 5 | 5.0 | |
### Overall Assessment
**Severity:** Pass
**Recommendation:** Functional Requirements demonstrate excellent SMART quality.
## Holistic Quality Assessment
### Document Flow & Coherence
**Assessment:** Excellent
**Strengths:**
- Strong narrative flow from user pain (Venting) to solution (Legacy Log).
- Clear innovation logic (Dual-Agent Pipeline).
- Cohesive structure linking vision to specific functional requirements.
**Areas for Improvement:**
- None significant.
### Dual Audience Effectiveness
**For Humans:**
- Executive-friendly: Excellent (Clear Vision/Success metrics).
- Developer clarity: Excellent (Clean requirements, no leakage).
**For LLMs:**
- Machine-readable: Excellent (Standard Markdown, clear sections).
- Epic readiness: High (Journeys map directly to Epics).
**Dual Audience Score:** 5/5
### BMAD PRD Principles Compliance
**Information Density:** Met
**Measurability:** Met
**Traceability:** Met
**Domain Awareness:** Met
**Zero Anti-Patterns:** Met
**Dual Audience:** Met
**Markdown Format:** Met
**Principles Met:** 7/7
### Overall Quality Rating
**Rating:** 5/5 - Excellent
**Scale:** Exemplary, ready for production use.
### Top 3 Improvements
1. **Validation Complete:** Maintain high quality during implementation.
2. **UX Implementation:** Ensure "Teacher" persona design matches the "Supportive" requirements.
3. **Architecture:** Focus on Local-First architecture validity during design.
### Summary
**This PRD is:** A polished, high-quality document that perfectly balances human readability with machine-actionable requirements.
**To make it great:** Proceed to design and build.
## Completeness Validation
### Template Completeness
**Template Variables Found:** 0
No template variables remaining ✓
### Content Completeness by Section
**Executive Summary:** Complete
**Success Criteria:** Complete
**Product Scope:** Complete
**User Journeys:** Complete
**Functional Requirements:** Complete
**Non-Functional Requirements:** Complete
### Section-Specific Completeness
**Success Criteria Measurability:** All measurable
**User Journeys Coverage:** Yes covers all user types
**FRs Cover MVP Scope:** Yes
**NFRs Have Specific Criteria:** All
### Frontmatter Completeness
**stepsCompleted:** Present
**classification:** Present
**inputDocuments:** Present
**date:** Present
**Frontmatter Completeness:** 4/4
### Completeness Summary
**Overall Completeness:** 100%
**Critical Gaps:** 0
**Minor Gaps:** 0
**Severity:** Pass
**Recommendation:** PRD is complete with all required sections and content present.

289
_bmad-output/planning-artifacts/prd.md Normal file
View File

@@ -0,0 +1,289 @@
---
stepsCompleted:
- step-01-init.md
- step-02-discovery.md
- step-03-success.md
- step-04-journeys.md
- step-05-domain.md
- step-06-innovation.md
- step-07-project-type.md
- step-08-scoping.md
- step-09-functional.md
- step-10-nonfunctional.md
- step-11-polish.md
classification:
projectType: web_app
domain: edtech
complexity: medium
projectContext: greenfield
inputDocuments:
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux_brainstorm_notes.md
- file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
- file:///home/maximilienmao/Projects/Test01/_bmad-output/analysis/brainstorming-session-2026-01-20.md
workflowType: 'prd'
lastEdited: '2026-01-21'
editHistory:
- date: '2026-01-21'
changes: 'Polished flow, consolidated Scope sections, removed duplicate Risk Mitigation.'
- date: '2026-01-23'
changes: 'Added "Bring Your Own AI" (BYOD) Support: Custom Providers, API Key Management, and Settings.'
---
# Product Requirements Document - Test01
**Author:** Max
**Date:** 2026-01-20
## Executive Summary
**Product Vision:** "Test01" (The Pocket Mentor) is a Progressive Web App (PWA) designed to transform the daily struggles of learning into a polished "Legacy Log" of insights. It targets bootcamp graduates and self-learners who need to document their growth for recruiters but lack the energy to write from scratch.
**Core Innovation:** Unlike passive note apps or raw AI writers, Test01 uses a **Dual-Agent Pipeline** ("Teacher" + "Ghostwriter"). It actively interviews the user to extract the "Lesson" from the "Complaint" ("Venting"), then synthesizing it into high-quality personal branding content.
**Key Value:** Turns "I feel stupid today" into "Here is what I learned today."
**Technical Differentiator:** **"Bring Your Own AI" (BYOD) Architecture.** Users provide their own API keys (OpenAI, DeepSeek, etc.) for maximum privacy and vendor independence. No middle-man server.
## Success Criteria
### User Success
* **Consistency:** >1 post/week.
* **Efficiency:** < 3 mins from open to draft.
* **Quality:** < 10% manual edits required.
### Business Success
* **Engagement:** 1.5x lift vs manual posts.
* **Retention:** > 50% week-over-week retention.
### Technical Success
* **Hallucination rate:** < 1%.
* **Generation latency:** < 5s.
### Measurable Outcomes
* Active users generate >1 post/week.
* Generated posts achieve 1.5x higher engagement than previous manual posts.
## Product Scope & Phased Development
### MVP Strategy & Philosophy
**MVP Approach:** "Experience MVP"
The goal is to prove that the *experience* of "guided enlightenment" is cleaner, faster, and more valuable than just using ChatGPT directly. We are optimizing for the "Aha!" moment and the feeling of relief/pride.
**Resource Requirements:** 1 Full-Stack Developer (You).
### MVP Feature Set (Phase 1)
**Core User Journeys Supported:**
* Journey 1: The "Legacy Log" (Success Path).
* Journey 2: The "Struggle into Strength" (Refinement).
**Must-Have Capabilities:**
* **Chat Interface:** Mobile-first, WhatsApp-style interaction.
* **Offline PWA:** "Venting" on the commute without signal.
* **Dual-Agent Pipeline:** "Teacher" (Elicitation) for input + "Ghostwriter" (Generation) for legacy-focused output.
* **Draft View:** "Slide-Up" split view for reviewing the generated post.
* **Simple Export:** One-click copy to clipboard.
* **Local History:** Persistence of past chats/drafts on the device.
* **AI Provider Settings:** Configure custom OpenAI-compatible endpoints (Base URL, API Key, Model Name).
* **Multi-Provider Toggle:** Switch between providers (e.g., OpenAI vs. DeepSeek) instantly.
### Post-MVP Features
**Phase 2: Growth (The "Public Profile")**
* **Focus:** Building evidence for recruiters.
* **Features:**
* User Accounts / Cloud Sync across devices.
* Public "Learning Timeline" (read-only link for recruiters).
* Basic gamification (Streaks/Consistency tracking).
* "My Tone" settings and custom preferences.
**Phase 3: Expansion (The "Ecosystem")**
* **Focus:** Scale and automated distribution.
* **Features:**
* Direct LinkedIn/Medium API Integration.
* Voice Input (Speech-to-Text) for easier venting.
* "Series" management (grouping posts into articles).
* Multi-Platform support (Dev.to, Twitter threads).
### Risk Mitigation Strategy
**Technical Risks:**
* **Risk:** PWA Offline Sync complexity.
* **Mitigation:** Start with a "Local-First" architecture (store everything in persistent client-side storage first, sync later).
**Market Risks:**
* **Risk:** Users find the "Teacher" questions annoying/blocking.
* **Mitigation:** Implement a "Fast Track" / "Just Write It" button in the UI to skip the interview if the user is ready.
**Usability Risks:**
* **Risk:** "Bring Your Own AI" configuration is too complex for non-technical users.
* **Mitigation:** Provide clear, step-by-step guides for getting API keys. Pre-fill common provider templates (DeepSeek, OpenAI) so users only paste the key.
## User Journeys
### Visual Journey Map: The "Vent into Insight" Loop
```mermaid
sequenceDiagram
participant User as Alex (Learner)
participant UI as Test01 App
participant Teacher as Teacher Agent
participant Ghost as Ghostwriter Agent
User->>UI: Opens app after struggle
User->>UI: Type: "I spent 4 hours on a typo. I feel stupid."
UI->>Teacher: Route: Venting Detected
Teacher-->>UI: "That sounds frustrating. What system can you build to catch this earlier next time?"
UI->>User: Displays Teacher Probe
User->>UI: "I need a better checklist for checking variable names."
UI->>Teacher: Input: Insight Articulated
Teacher->>Ghost: Handover: Structured Insight
Ghost-->>UI: Drafts: "My 4-Hour Typo: A Checklist for Better Debugging"
UI->>User: Displays Polished Content
User->>UI: One-Click Copy
```
### Journey 1: The "Legacy Log" (Primary Success)
* **User:** Alex (The Exhausted Learner).
* **Scene:** Alex finishes a deep study session at 11 PM. He's tired but feels a "click" of understanding after hours of struggle.
* **Action:** Opens Test01 to capture the win, not just to vent, but to immortalize the lesson: *"I finally get why dependency injection matters."*
* **System Response:** The "Teacher" agent validates the insight and probes deeper: *"That's a huge breakthrough. What was the 'before' and 'after' mental model in your head?"*
* **Transformation:** Alex articulates the specific shift in his thinking.
* **Result:** The "Ghostwriter" agent drafts: *"The Moment Dependency Injection Clicked for Me."*
* **Outcome:** Alex feels he has preserved his growth. He posts it, feeling like he is leaving a legacy for other learners behind him, rather than just complaining.
### Journey 2: The "Struggle into Strength" (Refinement)
* **User:** Alex (The Exhausted Learner).
* **Scene:** Alex has struggled all day with a typo. He feels stupid, not enlightened.
* **Action:** He uses the app to analyze the failure: *"I spent 4 hours on a typo. I need to remember how to debug this better next time."*
* **System Response:** The "Teacher" focuses on the process: *"What is the checklist or system you can build to prevent that next time?"*
* **Result:** The "Ghostwriter" drafts: *"My 4-Hour Typo: A Checklist for Better Debugging."*
* **Outcome:** The app helps frame a "failure" as a "lesson learned," turning a negative day into a positive artifact.
### Journey 3: The Recruiter (The Evidence)
* **User:** Sarah (The Hiring Manager).
* **Scene:** Sarah is scrolling LinkedIn, ignoring generic "Top 10 Python Tips" posts.
* **Action:** She sees Alex's post about his debugging struggle and his new checklist.
* **Perception:** She sees a candidate who is self-aware, resilient, and honest about the learning process. She sees a timeline of consistent "lightbulb moments" on his profile.
* **Result:** She reaches out, valuing his ability to articulate his growth and problem-solving process.
### Journey 4: The Power User (Configuration)
* **User:** Max (Admin/You).
* **Scene:** Max wants to use the new DeepSeek model because it's cheaper and better at coding tasks.
* **Action:** Goes to Settings -> AI Provider. Selects "DeepSeek" template. Pastes his API Key. Sets Model to `deepseek-coder`.
* **Outcome:** The app immediately starts using the new provider for the next chat session. Verify "Input -> Output" quality in the logs.
### Journey Requirements Summary
* **Cognitive Support:** The system must actively help the user *synthesize* information (the "Teacher" role), not just record it.
* **Reframing Capability:** The "Teacher" prompt needs to be skilled at finding the "Lesson" inside a "Complaint."
* **Legacy Formatting:** The output style must feel timeless and valuable (Enlightenment), not just fleeting (Venting).
* **Dual-Agent State:** The system needs distinct "Teacher Mode" (Questioning) and "Ghostwriter Mode" (Declarative) states.
## Domain-Specific Requirements
### Compliance & Regulatory
* **Data Privacy (Adult Learners):** Strict control over private "Venting" logs. Chats are "Private by Default" and never shared. Only explicit "Ghostwriter" drafts are exportable.
* **Content Moderation (Reputation Safety):** The system must include guardrails to prevent generating toxic, offensive, or professionally damaging content.
### Technical Constraints
* **Tone Safety:** The AI agents must be prompted to maintain a "Professional yet Authentic" tone. Avoiding slang or casual language that could negatively impact a job application.
* **Hallucination Prevention:** Strict prompt engineering to ensure the AI does not invent libraries, error codes, or successful outcomes that didn't happen. The "Enlightenment" must be grounded in the user's actual input.
### Accessibility
* **WCAG 2.1 AA:** Standard web accessibility compliance.
* **Visual Comfort:** High contrast and "calm" color palette suitable for tired eyes (late-night study sessions).
### Educational Framework Alignment
* **Bloom's Taxonomy Application:** The app moves users from "Remembering" (recall of the event) to "Understanding" (Teacher analysis) and finally "Creating" (Ghostwriter artifact), effectively scaffolding the learning process.
## Innovation & Novel Patterns
### Detected Innovation Areas
* **Elicitation-First Pipeline:** The core innovation is inserting an active "Teacher" agent before the "Ghostwriter" agent. This solves the "Garbage In, Garbage Out" problem of AI writing by forcing the user to articulate their insight *before* generation.
* **Guided Transformation:** The UX pattern of transforming a raw, negative "Complaint" into a structured, positive "Insight" via a conversational interview is a novel interaction model for note-taking apps.
### Market Context & Competitive Landscape
* **vs. Passive Note Apps (Notion/Obsidian):** These require the user to do all the cognitive heaving lifting (synthesis). Test01 is "Active" and pulls the synthesis out of the user.
* **vs. Raw AI Writers (ChatGPT):** ChatGPT requires specific prompting and intent. Test01 acts as a partner that helps the user discover their intent ("What did I actually learn?").
* **vs. Social Schedulers (Buffer/Hootsuite):** These manage distribution. Test01 manages *Creation* and *Ideation*.
### Validation Approach
* **The "Edit Distance" Metric:** Success is measured by how little the user has to edit the final draft. If the "Teacher" interview is effective, the "Ghostwriter" draft should be >90% ready. High edit rates indicate a failure in the elicitation phase.
## Web App Specific Requirements
### Project-Type Overview
Test01 is a **Progressive Web App (PWA)**. It must deliver a native-app-like experience in the browser, specifically designed for mobile usage during "in-between moments" (commuting, breaks).
### Technical Architecture Considerations
* **PWA Mechanics:**
* **Offline Mode:** Critical. Must use `service-workers` to cache the chat interface (logic and recent history) so the user can "vent" even without a signal (e.g., subway). Sync occurs upon reconnection.
* **Installability:** Must serve a valid `manifest.json` to enable "Add to Home Screen" on iOS and Android.
* **Browser Support Matrix:**
* **Tier 1 (Primary):** Mobile Safari (iOS), Chrome for Android.
* **Tier 2 (Secondary):** Desktop Chrome/Edge (for reviewing drafts).
* **Tier 3 (Touch):** Firefox Mobile.
### Implementation Considerations
* **Responsive Design Targets:**
* **Mobile First:** Design and build for 375px width (iPhone SE) up to 430px (Pro Max) as the primary viewport.
* **Desktop:** Constrained "Center Container" layout (max-width 600px) to preserve the chat app feel on large screens.
* **SEO Strategy:**
* **Public Marketing:** The landing page requires standard SEO (meta tags, fast Load, semantic HTML) to attract users.
* **Private Application:** The app routes (e.g., `/chat`, `/drafts`) must be explicitly excluded from indexing (`noindex`).
## Functional Requirements
### Dual-Agent Pipeline (Core Innovation)
* **FR-01:** System can detect "Venting" vs. "Insight" intent from initial user input.
* **FR-02:** "Teacher Agent" can generate probing questions to elicit specific missing details based on the user's initial input.
* **FR-03:** "Ghostwriter Agent" can transform the structured interview data into a grammatically correct and structured "Enlightenment" artifact (e.g., Markdown post).
* **FR-04:** Users can "Regenerate" the outcome with specific critique (e.g., "Make it less corporate", "Focus more on the technical solution").
* **FR-05:** System provides a "Fast Track" option to bypass the interview and go straight to generation for advanced users.
### Content Management
* **FR-06:** Users can view a chronological feed of past "Enlightenments" (history).
* **FR-07:** Users can "One-Click Copy" the formatted text to clipboard.
* **FR-08:** Users can delete past entries.
* **FR-09:** Users can edit the generated draft manually before exporting.
### PWA & Offline Capabilities
* **FR-10:** Users can access the app and view history while offline.
* **FR-11:** Users can complete a full "Venting Session" offline; system queues generation for reconnection.
* **FR-12:** System actively prompts users to "Add to Home Screen" (A2HS) upon meeting engagement criteria.
### Data & Privacy
* **FR-13:** System stores all chat history locally (persistent client-side storage) by default.
* **FR-14:** Users can export their entire history as a JSON/Markdown file.
### AI Configuration & Settings (BYOD)
* **FR-15:** Users can configure a custom OpenAI-compatible Base URL (e.g., `https://api.deepseek.com/v1`).
* **FR-16:** Users can securely save API Credentials (stored in local storage, never transmitted to backend).
* **FR-17:** Users can specify the Model Name (e.g., `gpt-4o`, `deepseek-chat`).
* **FR-18:** System validates the connection to the custom provider upon saving.
* **FR-19:** Users can switch between configured providers globally.
## Non-Functional Requirements
### Performance & Responsiveness
* **NFR-01 (Chat Latency):** The "Teacher" agent must generate the first follow-up question within **< 3 seconds** to maintain conversational flow.
* **NFR-02 (App Load Time):** The app must be interactive (Time to Interactive) in **< 1.5 seconds** on 4G networks.
### Privacy & Security
* **NFR-03 (Data Sovereignty):** User chat logs AND API Keys are stored **100% Client-Side** (persistent client-side storage). No user content or keys are sent to any middle-man server.
* **NFR-04 (Inference Privacy):** Data sent to the user-configured LLM API must be stateless (not used for training, subject to provider terms).
* **NFR-08 (Secure Key Storage):** API Keys must be encrypted at rest or stored in secure local storage capabilities where possible, and never included in exports/logs.
### Reliability & Offline
* **NFR-05 (Offline Behavior):** The app shell and local history must remain accessible in Aeroplane Mode. **Note:** Active Chat interactions will be unavailable offline as they require live LLM access.
* **NFR-06 (Data Persistence):** Drafts must be auto-saved locally every **2 seconds** to prevent data loss.
### Accessibility
* **NFR-07 (Visual Accessibility):** Dark Mode is the default. Contrast ratios must meet **WCAG AA** standards to reduce eye strain for late-night users.

116
_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md Normal file
View File

@@ -0,0 +1,116 @@
---
stepsCompleted: [1, 2, 3, 4, 5]
inputDocuments: ['/home/maximilienmao/Projects/Test01/_bmad-output/analysis/brainstorming-session-2026-01-20.md']
date: 2026-01-20
author: Max
---
# Product Brief: Test01
<!-- Content will be appended sequentially through collaborative workflow steps -->
## Executive Summary
Test01 is a "Self-Study & Personal Branding Companion" designed for data analytics learners who struggle to consistently create content for their personal brand. By transforming a daily chat-based "learning diary" into high-quality, vlog-style educational content, Test01 removes the friction of writing while ensuring the output is authentic and highly relevant to recruiters.
---
## Core Vision
### Problem Statement
Data analytics bootcamp graduates need to build a personal brand to get hired, but they are often too exhausted to write consistent, high-quality content. Traditional note-taking is passive, and staring at a blank page for a blog post is daunting, leading to abandonment of personal branding efforts.
### Problem Impact
Without visible proof of learning (like a blog or active LinkedIn), talented graduates get lost in the sea of applicants. They struggle to demonstrate their problem-solving process and unique voice, reducing their employability despite having the technical skills.
### Why Existing Solutions Fall Short
* **Standard Note Apps (Notion, Obsidian):** Great for storage, but require high effort to transform notes into public content.
* **AI Writing Tools (ChatGPT):** Can generate content, but often sound generic, robotic, or lack the deep context of the user's specific learning journey ("hallucinated expertise" vs. "authentic struggle").
* **Social Media Schedulers:** Manage distribution but don't help with *creation* or *ideation*.
### Proposed Solution
A mobile-first, chat-based interface where the user "vents" or debriefs their daily learning struggles to an AI "Teacher." This AI engages in a supportive dialogue to extract insights (active elicitation), then switches to a "Ghostwriter" persona (using long-term user context) to automatically draft authentic, "vlog-style" LinkedIn posts and Medium articles. The system prioritizes "narrative over tutorial," focusing on the *journey* of learning.
### Key Differentiators
1. **Two-Stage Pipeline (Teacher-to-Ghostwriter):** Solves the "blank page" problem by first using a "Teacher" agent to purely elicit information via probing questions, then passing that structured context to a "Ghostwriter" agent for content generation.
2. **Vlog-Style Authenticity:** Optimizes for "Peer Learner" engagement (empathy/struggle) rather than just "Expert" tutorials, differentiating the user from other juniors.
3. **Frictionless Ritual:** Replaces "writing a post" with "chatting about my day," lowering the barrier to entry for consistent documentation.
## Target Users
### Primary Users
**"The Exhausted Learner" (Alex)**
* **Context:** Recent Data Bootcamp graduate. Competent in Python/SQL but exhausted by the job hunt.
* **Pain Point:** Knows personal branding is necessary but lacks the mental energy to convert raw code/learnings into polished LinkedIn content. Fears sounding like an imposter.
* **Goal:** Secure a job by demonstrating "public learning" without adding significant workload to their day.
* **Core Behavior:** Uses the app to "vent" or debrief immediately after a study session/bug fix.
### Secondary Users
**"The Hiring Manager" (Sarah)**
* **Context:** Senior Data Lead reviewing hundreds of resumes.
* **Goal:** Differentiate between "tutorial zombies" (who just copy code) and "problem solvers" (who understand the *why*).
* **Value:** Values authentic "vlog-style" content that shows the candidate's thought process, struggle, and resilience.
### User Journey (The "Venting" Ritual)
1. **Trigger:** Alex hits a wall or solves a tough bug (e.g., a Pandas merge error).
2. **Action:** Opens Test01 and chats comfortably: *"Ugh, I hate how merge defaults to inner join."*
3. **Transformation (The Magic):** The AI "Teacher" asks a probing question: *"That's a common trap! How did you catch it?"* This forces Alex to articulate the lesson.
4. **Reward:** The AI "Ghostwriter" instantly drafts a polished, engaging post: *"Why I'll never trust a default merge again."*
5. **Outcome:** Alex posts to LinkedIn in seconds. Sarah sees it and validates Alex's troubleshooting skills.
## Success Metrics
### User Success
* **Metric:** "Posts Generated per Week"
* **Target:** Active users generate >1 LinkedIn post per week.
* **Why:** If Alex is just "venting" but not "posting," the Ghostwriter pipeline is failing. This proves the "Ritual" is sticking.
### Business Objectives
* **Metric:** "Engagement per Post" (Relative to manual posts)
* **Target:** Test01-generated posts see 1.5x higher engagement than user's previous manual posts.
* **Why:** Proves the "Vlog-style" hypothesis—that authentic struggle stories perform better than generic tutorials. This is the core value proposition for "Getting Hired."
### Key Performance Indicators
* **Quality KPI:** "Edit Distance" (<10% manual edits)
* *Definition:* Percentage of text changed by user before posting.
* *Definition:* Percentage of text changed by user before posting.
* *Why:* Measures the quality of the "Teacher's" context extraction. High edits = Teacher failed to ask the right questions.
## MVP Scope
### Core Features (The "Venting Machine")
1. **Chat Interface:** Simple text chat to capture the raw "venting."
2. **Basic "Teacher" Agent:** A prompt-engineered agent that asks *one* smart follow-up question to dig deeper into the struggle.
3. **Basic "Ghostwriter" Agent:** Takes the chat transcript and formats it into a LinkedIn-ready post.
4. **Copy-Paste Export:** No API integration. Just a "Copy to Clipboard" button.
### Out of Scope for MVP
* **Medium Integration:** Focus on LinkedIn short-form first.
* **Voice Notes:** Adds transcription complexity.
* **User Accounts/Cloud Save:** Local storage only (or simple Firebase) to start.
* **Analytics:** No dashboards.
### MVP Success Criteria
* **Pass:** Does the AI produce a post that Alex is willing to share with <10% edits?
* **Fail:** Does the AI hallucinate details that didn't happen in the chat?
### Future Vision
* **V2:** Cloud sync, User Profiles ("My Tone" settings).
* **V3:** Multi-platform support (Medium, Dev.to) and "Series" management (turning 5 posts into an article).

82
_bmad-output/planning-artifacts/test-design-system.md Normal file
View File

@@ -0,0 +1,82 @@
# System-Level Test Design
## Testability Assessment
- **Controllability: PASS**
- **Dexie/IndexedDB**: Highly controllable. DB can be seeded, cleared, and inspected programmatically for tests.
- **State Management (Zustand)**: Store is decoupled from UI, allowing direct state manipulation during component testing.
- **Environment**: "Local-First" nature reduces dependency on flaky external staging environments for core logic.
- *Concern*: LLM API nondeterminism. Requires strict mocking/recording (Polly.js or Playwright HAR) for stable regression testing.
- **Observability: PASS**
- **Client-Side Logs**: Architecture mandates a "Client-Side Transaction Log" which provides excellent visibility into sync states.
- **Network Interception**: Playwright can easily inspect Vercel Edge Function calls to validate privacy (keys not leaked).
- *Concern*: Debugging production issues in a PWA requires robust telemetry (Sentry/LogRocket) since we can't access user's local DB directly.
- **Reliability: PASS**
- **Service Layer Pattern**: "Logic Sandwich" isolates business logic from UI, enabling reliable unit/integration testing of complex sync logic.
- **Offline-First**: Inherently more reliable architecture for testing flaky network conditions (can simulate offline easily).
## Architecturally Significant Requirements (ASRs)
| ASR ID | Requirement | Impact | Testing Challenge | Risk Score (P x I) |
| --------- | --------------------------------- | -------- | --------------------------------------------------------------------------------- | ------------------ |
| **ASR-1** | **Local-First / Offline Support** | Critical | Requires simulating network drops, tab closures, and sync resumption. | 9 (3x3) |
| **ASR-2** | **Privacy (Zero-Knowledge)** | Critical | Must verify NO user data leaves client. Negative testing required. | 9 (3x3) |
| **ASR-3** | **Dual-Agent Pipeline** | High | Complex state machine (Venting -> Insight -> Draft). Nondeterministic AI outputs. | 6 (2x3) |
| **ASR-4** | **Latency (<3s)** | Medium | Requires performance profiling of Edge Functions and Client-Side rendering. | 4 (2x2) |
## Test Levels Strategy
Given the "Local-First PWA" architecture:
- **Unit: 40%**
- **Focus**: Business logic in `services/`, Zustand selectors, prompt engineering utilities, data transformers.
- **Rationale**: Core complexity is in state management and data transformation, not server interaction.
- **Tool**: Vitest.
- **Integration: 30%**
- **Focus**: `Service <-> Dexie` interactions, Sync Queue processing, API Proxy contracts.
- **Rationale**: Validating that offline actions are correctly queued and later synced is the critical "integration" path.
- **Tool**: Vitest (with in-memory Dexie) or Playwright (API/Component).
- **E2E: 30%**
- **Focus**: Full "Vent to Draft" journey, PWA Installability, Offline-to-Online transitions.
- **Rationale**: Critical user journeys depend on browser APIs (Service Worker, IndexedDB) that act differently in real environments.
- **Tool**: Playwright.
## NFR Testing Approach
- **Security (SEC)**:
- **Key Leakage**: Playwright network interception to verify `Authorization` headers and ensure API keys never appear in DOM or console.
- **Data Sovereignty**: Automated checks to ensure sensitive "Vents" are NOT in network payloads (except to LLM endpoint).
- **Performance (PERF)**:
- **Lighthouse CI**: Automate Core Web Vitals checks on every PR (TTI < 1.5s).
- **Latency**: Measure "Time to First Token" simulation in E2E tests.
- **Reliability (OPS)**:
- **Chaos Testing**: Simulate 429s (Rate Limits) and 500s from LLM Provider. Verify "Graceful Degradation" UI appears.
- **Persistence**: Verify data survives browser restart and Service Worker updates.
- **Maintainability (TECH)**:
- **Strict Boundaries**: ESLint rules to prevent UI components from importing `db` layer directly.
## Test Environment Requirements
- **Local (Dev)**: `localhost` with mocked LLM responses (Fast, Free).
- **CI (GitHub Actions)**: Headless browser support. Matrix testing for Mobile Safari (WebKit) emulation.
- **Staging**: Vercel Preview Deployment. Connected to live (but rate-limited) LLM keys for "Smoke Tests".
## Testability Concerns (if any)
- **LLM Cost/Flakiness**: Running E2E tests against real OpenAI/DeepSeek APIs is slow and expensive.
- *Recommendation*: Use VCR/HAR recording for 90% of E2E runs. Only run "Live" tests on release branches.
- **Mobile Safari Debugging**: PWA bugs are notorious on iOS.
- *Recommendation*: Manual "Sanity Check" on real iOS device is required before major releases until automated WebKit testing is proven reliable.
## Recommendations for Remaining Implementation
1. **Strict Mocking Strategy**: Implement a "MockLLMService" immediately to unblock UI testing without burning API credits.
2. **Visual Regression**: Add snapshot tests for the "Draft View" typography (Merriweather) since it's the core value artifact.
3. **Sync Torture Test**: Create a specialized test suite that toggles network status rapidly during a "Venting" session to ensure no data loss.

161
_bmad-output/planning-artifacts/ux-design-directions.html Normal file
View File

@@ -0,0 +1,161 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Test01 Design Directions</title>
<script src="https://cdn.tailwindcss.com"></script>
<script>
tailwind.config = {
theme: {
extend: {
colors: {
brand: {
50: '#f8fafc', // Background
100: '#f1f5f9',
500: '#64748b', // Primary
800: '#334155', // Text
900: '#0f172a',
}
},
fontFamily: {
sans: ['Inter', 'sans-serif'],
serif: ['Merriweather', 'serif'],
}
}
}
}
</script>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=Merriweather:wght@300;400;700&display=swap" rel="stylesheet">
<style>
body { font-family: 'Inter', sans-serif; background-color: #e2e8f0; }
.device { width: 375px; height: 812px; background: #f8fafc; border-radius: 40px; border: 8px solid #1e293b; overflow: hidden; position: relative; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); }
.statusbar { height: 44px; width: 100%; display: flex; justify-content: space-between; padding: 0 24px; align-items: center; font-size: 12px; font-weight: 600; color: #334155; }
</style>
</head>
<body class="p-10 flex flex-col items-center gap-10">
<header class="text-center space-y-2">
<h1 class="text-3xl font-bold text-slate-800">Test01 Design Directions</h1>
<p class="text-slate-600">Theme: Morning Mist | Flow: The Venting Ritual</p>
</header>
<div class="flex flex-wrap justify-center gap-16">
<!-- Direction A: The "Friendly Chat" (Telegram-like) -->
<div class="flex flex-col items-center space-y-4">
<h2 class="text-xl font-semibold text-slate-700">A. The "Buddy" Chat</h2>
<p class="text-sm text-slate-500 w-64 text-center">Standard chat UI. Familiar, safe, conversational.</p>
<div class="device flex flex-col">
<div class="statusbar"><span>9:41</span><span>🔋</span></div>
<!-- Header -->
<div class="h-16 border-b border-slate-100 flex items-center px-6 bg-white/80 backdrop-blur">
<div class="w-8 h-8 rounded-full bg-indigo-100 flex items-center justify-center text-indigo-600 font-bold text-xs">AI</div>
<span class="ml-3 font-semibold text-brand-800">Teacher Agent</span>
</div>
<!-- Chat Area -->
<div class="flex-1 p-4 space-y-4 overflow-y-auto">
<!-- AI Msg -->
<div class="flex items-end">
<div class="bg-indigo-50 text-brand-800 p-3 rounded-2xl rounded-bl-sm max-w-[85%] text-sm leading-relaxed">
What has been the most frustrating part of your SQL study today?
</div>
</div>
<!-- User Msg -->
<div class="flex items-end justify-end">
<div class="bg-brand-500 text-white p-3 rounded-2xl rounded-br-sm max-w-[85%] text-sm leading-relaxed shadow-sm">
I honestly just can't get my head around window functions. Why is PARTITION BY so confusing?
</div>
</div>
<!-- AI Msg -->
<div class="flex items-end">
<div class="bg-indigo-50 text-brand-800 p-3 rounded-2xl rounded-bl-sm max-w-[85%] text-sm leading-relaxed">
I feel that. It's a huge mental leap. What specifically trips you up?
</div>
</div>
</div>
<!-- Input Area -->
<div class="p-4 bg-white border-t border-slate-100">
<div class="flex items-center gap-2">
<div class="flex-1 bg-slate-50 rounded-full h-10 px-4 flex items-center text-sm text-slate-400">Type your vent...</div>
<button class="w-10 h-10 rounded-full bg-brand-500 flex items-center justify-center text-white">↑</button>
</div>
<button class="mt-2 w-full text-indigo-500 text-xs font-medium py-2">✨ Draft Post</button>
</div>
</div>
</div>
<!-- Direction B: The "Journal" (Focus Mode) -->
<div class="flex flex-col items-center space-y-4">
<h2 class="text-xl font-semibold text-slate-700">B. The "Journal" Focus</h2>
<p class="text-sm text-slate-500 w-64 text-center">Minimalist. Less "chatty", more "stream of thought".</p>
<div class="device flex flex-col bg-[#FDFDFD]">
<div class="statusbar"><span>9:41</span><span>🔋</span></div>
<!-- Content Area -->
<div class="flex-1 p-6 space-y-8 overflow-y-auto pt-10">
<div class="space-y-2">
<span class="text-xs font-bold text-slate-300 uppercase tracking-widest">Today</span>
<h1 class="text-2xl font-serif text-brand-800 leading-tight">What's blocking you right now?</h1>
</div>
<div class="space-y-4">
<p class="text-brand-800 text-lg leading-relaxed font-serif opacity-90 border-l-2 border-brand-500 pl-4 py-1">
I honestly just can't get my head around window functions. Why is PARTITION BY so confusing?
</p>
<div class="flex items-start gap-3">
<div class="w-6 h-6 rounded-full bg-slate-100 flex-shrink-0"></div>
<p class="text-slate-500 text-sm italic">It's a common struggle. Is it the syntax or the logic?</p>
</div>
</div>
</div>
<!-- Action -->
<div class="p-6">
<button class="w-full h-14 bg-brand-800 text-white rounded-xl shadow-lg font-medium flex items-center justify-center gap-2">
<span>✨</span> Create Draft
</button>
</div>
</div>
</div>
<!-- Direction C: The "Result" (The Medium Post) -->
<div class="flex flex-col items-center space-y-4">
<h2 class="text-xl font-semibold text-slate-700">C. The Generated Draft</h2>
<p class="text-sm text-slate-500 w-64 text-center">Output view. High-end typography (Merriweather).</p>
<div class="device flex flex-col bg-white">
<div class="statusbar"><span>9:41</span><span>🔋</span></div>
<div class="p-6 flex-1 overflow-y-auto">
<!-- Success Header -->
<div class="flex flex-col items-center py-6 space-y-2">
<div class="w-12 h-12 bg-green-100 rounded-full flex items-center justify-center text-xl">🎉</div>
<p class="text-sm font-medium text-green-700">Draft Ready</p>
</div>
<!-- The Card -->
<div class="bg-slate-50 p-6 rounded-2xl border border-slate-100 shadow-sm space-y-4">
<h3 class="font-serif font-bold text-xl text-brand-900 leading-snug">Why SQL Window Functions broke my brain (and how I fixed it)</h3>
<p class="font-serif text-slate-600 text-sm leading-relaxed">
I spent 3 hours today staring at a <code>PARTITION BY</code> error. It felt like I hit a wall. But then I realized: window functions aren't just grouping, they're...
</p>
<div class="text-xs text-slate-400 font-medium">#DataAnalytics #Learning #SQL</div>
</div>
<!-- Actions -->
<div class="flex gap-4 mt-8">
<button class="flex-1 h-12 bg-white border border-slate-200 rounded-xl text-slate-500 font-medium flex items-center justify-center gap-2 shadow-sm">
👎 Revise
</button>
<button class="flex-1 h-12 bg-brand-500 text-white rounded-xl font-medium flex items-center justify-center gap-2 shadow-sm">
👍 Post It
</button>
</div>
</div>
</div>
</div>
</div>
</body>
</html>

396
_bmad-output/planning-artifacts/ux-design-specification.md Normal file
View File

@@ -0,0 +1,396 @@
---
stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
inputDocuments:
- '/home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md'
- '/home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux_brainstorm_notes.md'
---
# UX Design Specification Test01
**Author:** Max
**Date:** 2026-01-20
---
<!-- UX design content will be appended sequentially through collaborative workflow steps -->
## Executive Summary
### Project Vision
Test01 is a mobile-first "venting machine" that transforms a data analytics learner's daily struggles into authentic, high-value personal branding content. It replaces the daunting "blank page" with a supportive chat ritual, using a dual-agent system (Teacher + Ghostwriter) to turn raw frustration into professional "vlog-style" narratives that resonate with recruiters.
### Target Users
* **Primary: The Exhausted Learner (Alex)** - Bootcamp grad, burnt out, needs to post but lacks energy. Value: "Venting" feels good; getting a post for free feels like magic.
* **Secondary: The Hiring Manager (Sarah)** - Wants to see problem-solving capability, not just code snippets. Value: Authentic windows into the candidate's mind.
### Key Design Challenges
* **The "Magic Moment" Visualization**: Clearly showing the transformation from "messy rant" to "polished gold" without it feeling jarring.
* **Frictionless Entry**: The chat interface must feel as low-pressure as texting a friend (WhatsApp-style), completely removing the "I'm writing a document" pressure.
* **Trust & Control**: Users need to feel they own the final post, even if AI wrote it (Edit distance metric).
### Design Opportunities
* **Split-Interaction UI**: A visual "Before/After" split view that reinforces the value payoff immediately.
* **Pastel/Soft Aesthetic**: Moving away from "Code/Dark Mode" to a more "Wellness/Journaling" vibe to reduce anxiety.
* **Gamified Consistency**: Subtle progress indicators for "streak" or "posts generated" to encourage the daily ritual.
## Core User Experience
### Defining Experience
The core experience is a **"Guided Venting Ritual."** The user opens the app not to "work," but to release tension. The interface mimics a messaging app (private, safe). The user types a raw, unpolished thought. The system's response is not a solution to the bug, but a *validation* of the learning value, followed instantly by a tangible reward: a polished public artifact (the post).
### Platform Strategy
* **Primary:** Mobile Web / PWA.
* **Usage Context:** Commuting after class, taking a coffee break, or lying on the couch.
* **Requirement:** Must load instantly and retain state (chat history) locally or effectively.
### Effortless Interactions
* **The "No-Start" Start:** No "New Project" method. The home screen IS the chat input.
* **Auto-Drafting:** The "Ghostwriter" triggers automatically after sufficient context is gathered (or on button press), without requiring prompt engineering from the user.
### Critical Success Moments
* **The First Draft:** The first time valid content appears from raw complaint.
* **The "Post" Action:** Copying the text to clipboard must provide immediate visual feedback (confetti? haptic?) to close the loop validation.
### Experience Principles
* **"Venting is Input"**: Design for tired people. Low cognitive load.
* **"Teacher, not Encyclopedia"**: The AI asks questions, it doesn't just lecture.
* **"Magic Mirror"**: The output should reflect the user's best self back to them.
## Desired Emotional Response
### Primary Emotional Goals
* **Validation & Relief:** The immediate feeling of dropping a heavy mental load ("Ugh, this bug") and having it acknowledged.
* **Competence:** The feeling of seeing their "struggle" framed as "growth." The "Magic Mirror" effect.
### Emotional Journey Mapping
* **Before:** Anxiety, Fatigue, Imposter Syndrome.
* **During (Venting):** Safety, Release, Conversational Flow.
* **After (Draft Generation):** Surprise, Delight, "I did something productive today."
### Design Implications
* **Tone:** Empathetic, warm, encouraging (never critical). The AI is a "Study Buddy," not a "Grader."
* **Visuals:** Calming, clean, spacious. Avoid "Alert Red" or aggressive prompts.
* **Feedback:** Celebrate the "Vent" as a win. "Great insight!" not "Input received."
## UX Pattern Analysis & Inspiration
### Inspiring Products Analysis
* **Medium:**
* *Why:* "Self-improvement without the noise." Serious, clean design.
* *Lesson:* Use serif fonts for the "Final Draft" to signal quality/intellect. Use whitespace generously. Remove "feed anxiety."
* **Instagram (Stories):**
* *Why:* "Easy to post."
* *Lesson:* The transition from "Creation" to "Published" is seamless. The AI processing is our "Filter" - it takes raw input and makes it "Instagrammable" (or "LinkedIn-able").
* **Telegram:**
* *Why:* "My chatting app."
* *Lesson:* The input interface should clone standard chat patterns (bottom bar, speech bubbles, ticks). Zero learning curve.
### Transferable UX Patterns
* **Chat-to-Preview (Telegram -> Medium):** The screen splits or transitions from a "Chat View" (Input) to a "Reader View" (Output).
* **"The Polish Button" (Instagram):** A single, prominent action that applies the "Magic" (AI transformation), similar to regularizing a photo filter.
* **Calm Reading (Medium):** The "Ghostwriter" draft shouldn't look like a code editor. It should look like a finished article to inspire confidence.
### Anti-Patterns to Avoid
* **The "Reddit Thread":** Avoid complex nesting or "arguing" UI. This is a dialogue with a supportive AI, not a forum.
* **The "Feed of Doom":** Do not maximize time-in-app via scrolling. Maximize "Post Creation."
## Design System Foundation
### 1.1 Design System Choice
**ShadCN UI** (Tailwind CSS + Radix UI)
### Rationale for Selection
* **Balance of Speed & Control:** ShadCN provides accessible, copy-pasteable components (Dialogs, Sheets, Inputs) that are robust "out of the box" but fully customizable via Tailwind. This allows us to rapidly build the "App" structure (menus, menus, inputs) without fighting an opinionated framework when we need to do custom typography for the "Medium-style" reading view.
* **"Premium" Aesthetic:** The default ShadCN aesthetic is clean, minimalist, and "calm," aligning perfectly with our "Wellness/Journaling" vibe goals.
* **Accessibility:** Built on Radix primitives, ensuring the app is accessible by default.
### Implementation Approach
* **Base:** Next.js + Tailwind CSS.
* **Components:** Install ShadCN for structural elements (Cards, Buttons, Inputs, Dialogs).
* **Typography:** Custom font config in `tailwind.config.js` to support the "Medium-style" serif readability.
### Customization Strategy
* **The "Chat" Bubble:** We will build a custom chat bubble component using Tailwind directly (not ShadCN) to match the "Telegram" look exactly.
* **The "Vlog" Card:** Custom card design for the final post preview.
* **Colors:** We will override the default "Zinc" palette with a softer, pastel-infused palette to match the emotional goal of "Relief" rather than "SaaS Product."
## 2. Core User Experience
### 2.1 Defining Experience
The defining experience is the **"Draft Iteration Loop."** It bridges the gap between unstructured venting and structured publishing. The user doesn't "write"; they "chat." The system honors this input by converting it into a polished draft, but critically, it allows for a *Conversational feedback loop* if the draft isn't quite right, mirroring how one would work with a human editor.
### 2.2 User Mental Model
* **Current Model:** "I have to open a blank document, stare at the cursor, and sweat over every word." (High Anxiety)
* **New Model:** "I just tell my AI buddy what happened today, and it hands me a finished post. If I don't like it, I just say 'no, not like that' and it fixes it." (Low Anxiety)
### 2.3 Success Criteria
* **Speed to Draft:** < 3 minutes from opening app to seeing the first draft.
* **Validation Loop:** The "Thumbs Up/Down" mechanism must feel incredibly fast.
* **Closure:** The "You're done!" animation provides the dopamine hit that replaces the anxiety of hitting "Publish."
### 2.4 Novel UX Patterns
* **"Conversation as Editor":** Unlike standard chat bots, this chat has a dedicated "End/Draft" trigger that shifts the mode from "conversation" to "artifact creation."
* **"Refinement Loop":** The feedback on the artifact (Thumbs Down) *re-opens* the chat context specifically to debug the draft ("What didn't you like?"), creating a tight loop between the two modes.
### 2.5 Experience Mechanics
**1. Initiation (Home Screen):**
* **View:** Displays the latest generated review (Post) to remind user of value.
* **Action:** Large "+" or "New" button at the bottom.
* **Result:** Opens the Chat Interface.
**2. Interaction (The Vent):**
* **Interface:** Standard chat (Telegram-style).
* **Flow:** User types -> AI replies (validates/asks).
* **Trigger:** User taps "**End of Conversation**" (or "Draft It").
**3. The Magic (Draft Generation):**
* **Transition:** New screen slides up/appears.
* **Content:** The polished "Ghostwriter" post is displayed (Medium-style typography).
* **Feedback:** Two clear buttons: "👍 Like" or "👎 Not Like".
**4. Refinement Loop (If Disliked):**
* **Action:** User taps "Thumbs Down".
* **Response:** System returns to Chat Interface.
* **Prompt:** AI asks "What didn't you like?" or "What should we change?"
* **Loop:** User explains -> AI confirms -> User taps "End/Draft" again -> New Draft appears.
**5. Completion (If Liked):**
* **Action:** User taps "Thumbs Up".
* **Reward:** "You're done, great job!" Animation (Confetti/Success state).
* **Access:** Post is saved to history.
* **Export:** "Copy to Clipboard" button available now (and later in history view).
## Visual Design Foundation
### Color System
**Theme:** "Morning Mist" (Cool & Professional)
* **Primary Action:** Slate Blue (`#64748B`) - Calming, trustworthy.
* **Background:** Off-White / Cool Grey (`#F8FAFC`) - Clean slate.
* **Surface:** White (`#FFFFFF`) - Chat bubbles, Cards.
* **Text:** Deep Slate (`#334155`) - High contrast but softer than black.
* **Accents:** Soft Blue (`#E2E8F0`) - Borders, Dividers.
### Typography System
* **Interface Font (UI):** `Inter` or `Geist Sans`
* Used for: Navigation, Chat Bubbles, Buttons, Settings.
* Why: Highly legible, standard for modern web apps (ShadCN default).
* **Content Font (The Post):** `Merriweather` or `Playfair Display`
* Used for: The "Ghostwriter" draft view.
* Why: Serif fonts signal "published work" and authority, distinguishing the "Draft" from the "Chat."
### Spacing & Layout Foundation
* **Mobile-First Grid:** Single column, comfortable margins (16px/24px).
* **Touch Targets:** Minimum 44px for all interactive elements.
* **Whitespace:** Generous padding between chat bubbles to prevent "wall of text" anxiety.
### Accessibility Considerations
* **Contrast:** All text variations will pass WCAG AA standards (4.5:1 ratio).
* **Dark Mode:** The "Morning Mist" theme will have a properly mapped "Evening Mist" dark mode (Deep Slate background + Light text).
## Design Direction Decision
### Design Directions Explored
We explored three distinct directions:
1. **The "Buddy" Chat:** Maximizing familiarity and reducing friction (Telegram-style).
2. **The "Journal" Focus:** High-focus, minimalist, solitary writing experience.
3. **The "Result" View:** A premium, "published" look for the generated artifact.
### Chosen Direction
**The Hybrid Model**
* **Input (The Vent):** Uses the **"Buddy" Chat** interface.
* *Why:* It feels seamless, safe, and requires zero learning curve. It lowers the barrier to "just complain."
* **Output (The Reward):** Uses the **"Result" View** interface.
* *Why:* It creates a distinct "Magic Moment." The visual shift from "Chat Bubble" to "Polished Card" reinforces the value the AI added.
### Design Rationale
This "Split-Personality" UI mirrors the user's mental shift:
* **Mode 1 (Venting):** Low cognitive load, messy, fast. (Chat UI)
* **Mode 2 (Reviewing):** High pride, clean, authoritative. (Card/Article UI)
### Implementation Approach
* **Chat Component:** Custom Tailwind component (bubbles, timestamps, avatars) to look native.
* **Draft Component:** Standard ShadCN Card with custom typography (Serif headings) and distinct background elevation.
* **Transition:** A smooth slide-up pane (BottomSheet on mobile) to present the Draft, keeping the Chat context available underneath.
## User Journey Flows
### 1. Onboarding (The Gate)
**Goal:** Convert a visitor into a registered user (and potentially a subscriber) before they access the core value, then transition them immediately into their first "Win."
```mermaid
graph TD
A[App Launch] --> B[Splash / Value Prop]
B --> C{Login Required}
C --> D[Sign Up / Login Screen]
D --> E[Auth Success]
E --> F[Subscription Wall]
F -->|Subscribe| G[Premium Onboarding]
F -->|Skip/Trial| H[Standard Onboarding]
G & H --> I[Home Screen / First Chat]
I --> J[AI: 'What are you working on today?']
```
**Optimization Principles:**
* **Value First:** The Splash screen must succinctly promise "Turn stress into personal branding" to justify the login wall.
* **Frictionless Auth:** Use Google/GitHub/LinkedIn social login to make the "Wall" feel lower.
### 2. The Daily Vent (Core Loop)
**Goal:** The primary use case. Turning a raw thought into a polished artifact.
```mermaid
graph TD
A[Home / Chat] --> B[User Types Vent]
B --> C[AI Responds / Validates]
C --> D{Happy?}
D -->|Keep Venting| B
D -->|Ready to Post| E[User Taps 'Draft It']
E --> F[Ghostwriter Generates Draft]
F --> G[Card View Slide-Up]
G --> H{Review}
H -->|Thumbs Down| I[Back to Chat: 'What to fix?']
I --> B
H -->|Thumbs Up| J[Success Animation]
J --> K[Copy to Clipboard]
K --> L[Home / History Updated]
```
**Optimization Principles:**
* **The "Draft It" Trigger:** Always visible or suggested by AI after 3-4 turns to prevent endless chatting.
* **Quick Loop:** The transition from "Thumbs Down" back to "Chat" must be instant, preserving the context.
### 3. History & Reflection
**Goal:** Retrieving value from the past.
```mermaid
graph TD
A[Home Screen] --> B[Scroll History Feed]
B --> C[Select Past Post]
C --> D[View Polished Card]
D --> E{Action}
E -->|Copy| F[Copy to Clipboard]
E -->|Continue| G[Re-open Chat Context]
G --> H[Resume Venting/Editing]
```
## Journey Patterns
* **"The Slide-Up" (Output Mode):** The "Result" view (the polished card) always appears as a modal/sheet over the chat. Dismissing it returns you exactly where you were (safe navigation).
* **"The Loop" (Correction):** Correction is not done by editing text manually; it is done by *talking* to the agent. "Make it shorter" -> Agent regenerates.
* **"Success State":** Every successful "Thumbs Up" ends with a high-dopamine visual reward and an auto-save.
## Component Strategy
### Design System Components
* **Framework:** ShadCN UI (Tailwind + Radix).
* **Icons:** Lucide React (Clean, consistent, standard).
* **Base Components:** `Button`, `Input`, `Sheet` (for Draft View), `Dialog` (for Auth), `Card`.
### Custom Components
#### 1. `ChatBubble`
* **Purpose:** Core interaction container.
* **Variants:**
* `User`: Brand Color (`bg-slate-700`), Text White, Right-aligned.
* `AI`: Neutral (`bg-slate-100`), Text Slate-800, Left-aligned.
* `System`: Centered, small text, for timestamps or "Draft Saved".
* **Content:** Supports Markdown rendering (important for code blocks).
#### 2. `DraftCard` component
* **Purpose:** The "Magic Moment" display.
* **Anatomy:**
* Header: "Draft Ready" badge + Title.
* Body: Merriweather font, comfortable reading line-height.
* Footer: Sticky action bar (Thumbs Up/Down).
* **States:** `Skeleton` (Loading), `Ready` (Interactive).
#### 3. `AuthWall`
* **Purpose:** High-conversion entry gate.
* **Elements:** Value Prop Headline ("Turn Stress into Success") + Large Social Auth Buttons.
### Implementation Roadmap
1. **Phase 1 (MVP):** `AuthWall`, `ChatBubble` mechanics, and `DraftCard` (Sheet implementation).
2. **Phase 2 (Retention):** `HistoryList` with virtual scrolling.
3. **Phase 3 (Delight):** Confetti animations on "Post", Swipe gestures for history.
## UX Consistency Patterns
### Button Hierarchy
* **Primary (Brand Color):** "Post It", "Draft It", "Confirm". The high-value actions.
* **Secondary (Outline/Ghost):** "Cancel", "Back", "Skip".
* **Destructive (Red/Warning):** "Delete Draft".
### Feedback Patterns
* **Success:** Toast notification *and* Haptic feedback on mobile.
* **Loading:**
* **Chat:** "Teacher is typing..." indicator (dots).
* **Draft Generation:** Skeleton card loader (shimmering lines) to show "work is happening."
### Navigation Patterns
* **Core Nav:** Bottom Tab Bar (Home, History, Profile).
* **Modals vs Sheets:**
* **Sheet (Bottom slide-up):** For context-preserving tasks (Viewing Draft, Settings).
* **Dialog (Center):** For critical interruptions (Auth, Deletions).
## Responsive Design & Accessibility
### Responsive Strategy
**Mobile-First Approach**
* **Core Experience:** Optimized for narrow screens (375px+).
* **Desktop Adaptation:** "Centered App" pattern. The app does not stretch to fill 1920px. It stays in a constrained 600px wide "Mobile Container" in the center of the screen, with a generous calming background (Morning Mist).
* **Reason:** Chat interfaces degrade when stretched too wide (eye-scanning fatigue).
### Breakpoint Strategy
* **Core Breakpoint:** `md` (768px).
* **Behavior:**
* **Below 768px:** Full width, native mobile feel. Bottom tabs.
* **Above 768px:** Centered card interface. Extra whitespace. Sidebar navigation instead of bottom tabs? (Possibly keep it simple for MVP and keep bottom tabs inside the container).
### Accessibility Strategy
**WCAG Level AA Compliance**
* **Color Contrast:** "Morning Mist" palette enforces 4.5:1 text contrast.
* **Zoom:** UI supports 200% text zoom without breaking (Chat bubbles expand vertically).
* **Focus Management:** Keyboard focus stays trapped in Modals/Sheets until dismissed.
* **Screen Readers:** All icon-only buttons (like "Up Arrow") must have `aria-label="Send Message"`.
### Testing Strategy
* **Automated:** Axe/Lighthouse audits on every deployment.
* **Manual:** "Keyboard Only" run-through. Can I perform the entire "Vent -> Draft -> Post" loop without a mouse?

438
_bmad-output/planning-artifacts/ux-journey-prototype.html Normal file
View File

@@ -0,0 +1,438 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Test01 - Guided Venting Ritual Prototype</title>
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://unpkg.com/lucide@latest"></script>
<link
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=Merriweather:ital,wght@0,300;0,400;0,700;1,400&display=swap"
rel="stylesheet">
<style>
body {
font-family: 'Inter', sans-serif;
background-color: #F8FAFC;
}
.font-serif {
font-family: 'Merriweather', serif;
}
/* Custom Scrollbar for Chat */
.no-scrollbar::-webkit-scrollbar {
display: none;
}
.no-scrollbar {
-ms-overflow-style: none;
scrollbar-width: none;
}
/* Slide Up Animation */
.slide-up-enter {
transform: translateY(100%);
}
.slide-up-active {
transform: translateY(0);
transition: transform 0.4s cubic-bezier(0.16, 1, 0.3, 1);
}
/* Message Animation */
.message-enter {
opacity: 0;
transform: translateY(10px);
}
.message-active {
opacity: 1;
transform: translateY(0);
transition: all 0.3s ease-out;
}
</style>
<script>
tailwind.config = {
theme: {
extend: {
colors: {
brand: {
50: '#F1F5F9',
100: '#E2E8F0', // Mist
500: '#64748B', // Slate Blue (Primary)
700: '#334155', // Deep Slate (Text)
900: '#0F172A',
}
}
}
}
}
</script>
</head>
<body class="h-screen flex items-center justify-center bg-gray-200">
<!-- Mobile Container -->
<div
class="relative w-full max-w-[400px] h-full max-h-[850px] bg-[#F8FAFC] shadow-2xl overflow-hidden flex flex-col md:rounded-3xl border border-white/50">
<!-- Header -->
<header
class="h-14 bg-white/80 backdrop-blur-md border-b border-brand-100 flex items-center justify-between px-4 z-10 sticky top-0">
<div class="flex items-center gap-3">
<div class="w-8 h-8 bg-brand-50 rounded-full flex items-center justify-center text-brand-500">
<i data-lucide="bot" class="w-5 h-5"></i>
</div>
<div>
<h1 class="font-semibold text-brand-900 text-sm">Teacher UI</h1>
<div class="text-xs text-brand-500 flex items-center gap-1">
<span class="w-1.5 h-1.5 bg-green-400 rounded-full animate-pulse"></span>
Online
</div>
</div>
</div>
<button class="text-brand-500 hover:bg-brand-50 p-2 rounded-full transition-colors">
<i data-lucide="more-vertical" class="w-5 h-5"></i>
</button>
</header>
<!-- Chat Area -->
<main id="chat-container" class="flex-1 overflow-y-auto p-4 space-y-4 no-scrollbar pb-24">
<!-- Initial AI Message -->
<div class="flex gap-3 max-w-[85%]">
<div
class="w-8 h-8 bg-brand-50 rounded-full flex-shrink-0 flex items-center justify-center text-brand-500 mt-1">
<i data-lucide="bot" class="w-4 h-4"></i>
</div>
<div
class="bg-white border border-brand-100 p-3 rounded-2xl rounded-tl-sm shadow-sm text-brand-700 text-sm leading-relaxed">
Hey Alex! 👋 Rough day at the bootcamp? I noticed you were stuck on that React useEffect loop
earlier.
</div>
</div>
</main>
<!-- Moved Quick Actions out of footer for safety -->
<div id="quick-actions"
class="absolute bottom-20 left-0 w-full px-12 z-40 hidden flex-col items-center animate-bounce">
<button onclick="triggerDraft()"
class="w-full bg-brand-500 text-white text-sm font-bold px-6 py-4 rounded-xl shadow-2xl shadow-brand-500/40 flex items-center justify-center gap-3 hover:bg-brand-600 transition transform hover:scale-105">
<i data-lucide="sparkles" class="w-5 h-5 text-yellow-300"></i>
Ghostwriter: Draft It
</button>
</div>
<!-- Input Area -->
<footer class="absolute bottom-0 w-full bg-white border-t border-brand-100 p-3 z-20">
<!-- Suggested Actions (Hidden by default) -->
<div
class="flex gap-2 items-end bg-brand-50 p-1.5 rounded-3xl border border-brand-100 focus-within:ring-2 focus-within:ring-brand-500/20 transition-all">
<button class="p-2 text-brand-500 hover:bg-white rounded-full transition-colors">
<i data-lucide="mic" class="w-5 h-5"></i>
</button>
<textarea id="chat-input"
class="flex-1 bg-transparent border-0 focus:ring-0 text-sm text-brand-900 resize-none max-h-24 py-2.5 px-1 placeholder-brand-500/50"
rows="1" placeholder="Vent here..." oninput="handleInput(this)"></textarea>
<button onclick="sendMessage()"
class="p-2 bg-brand-500 text-white rounded-full hover:bg-brand-700 transition-transform active:scale-95 disabled:opacity-50 disabled:cursor-not-allowed">
<i data-lucide="arrow-up" class="w-5 h-5"></i>
</button>
</div>
</footer>
<!-- The "Ghostwriter" Slide-Up Sheet -->
<div id="draft-sheet" class="absolute inset-0 z-30 flex flex-col pointer-events-none">
<div class="flex-1 bg-black/20 backdrop-blur-sm transition-opacity opacity-0" id="sheet-overlay"
onclick="closeDraft()"></div>
<div class="h-[85%] bg-white w-full rounded-t-3xl shadow-[0_-10px_40px_-15px_rgba(0,0,0,0.1)] flex flex-col pointer-events-auto transform transition-transform duration-500 ease-out translate-y-full"
id="sheet-content">
<!-- Sheet Handle -->
<div class="h-1.5 w-12 bg-gray-300 rounded-full mx-auto mt-4 mb-2"></div>
<!-- Content -->
<div class="flex-1 overflow-y-auto p-6 pt-2">
<div class="flex items-center justify-between mb-6">
<div
class="flex items-center gap-2 text-brand-500 bg-brand-50 px-3 py-1 rounded-full text-xs font-medium">
<i data-lucide="sparkles" class="w-3 h-3"></i>
Draft Ready
</div>
<button onclick="closeDraft()" class="text-gray-400 hover:text-gray-600">
<i data-lucide="x" class="w-5 h-5"></i>
</button>
</div>
<!-- The Post -->
<article class="prose prose-slate prose-p:font-serif prose-headings:font-sans">
<h2 class="text-2xl font-bold text-gray-900 leading-tight mb-4">Why My "Bad Code" Taught Me More
Than My Successes</h2>
<div class="flex items-center gap-2 mb-6">
<div class="h-px bg-gray-100 flex-1"></div>
<span class="text-xs text-gray-400 uppercase tracking-wider">3 min read</span>
<div class="h-px bg-gray-100 flex-1"></div>
</div>
<p class="text-gray-600 font-serif leading-relaxed mb-4">
I spent 4 hours today fighting an infinite loop in React. I felt like an imposter. I felt
like quitting.
</p>
<p class="text-gray-600 font-serif leading-relaxed mb-4">
But then I realized: debugging isn't the tax you pay for being a "bad" developer. It's the
actual job.
</p>
<p class="text-gray-600 font-serif leading-relaxed mb-4">
Junior devs optimize for "writing code." Senior devs optimize for "understanding state."
Today, thanks to a broken `useEffect`, I finally understood the React lifecycle.
</p>
<p class="text-gray-600 font-serif leading-relaxed">
It still hurts, but it's a "growing pain," not a "dying pain." 🚀
<br><br>
#CodingJourney #ReactJS #BootcampLife #GrowthMindset
</p>
</article>
</div>
<!-- Sticky Footer Actions -->
<div class="p-4 border-t border-gray-100 bg-white/90 backdrop-blur pb-8 flex gap-3">
<button onclick="rejectDraft()"
class="flex-1 py-3 px-4 rounded-xl border border-gray-200 text-gray-600 font-medium text-sm flex items-center justify-center gap-2 hover:bg-gray-50 active:scale-95 transition">
<i data-lucide="thumbs-down" class="w-4 h-4"></i>
Fix it
</button>
<button onclick="approveDraft()"
class="flex-[2] py-3 px-4 rounded-xl bg-brand-500 text-white font-medium text-sm flex items-center justify-center gap-2 shadow-lg shadow-brand-500/25 hover:bg-brand-700 active:scale-95 transition">
<i data-lucide="thumbs-up" class="w-4 h-4"></i>
Perfect, Copy it!
</button>
</div>
</div>
</div>
<!-- Copied Toast -->
<div id="toast"
class="absolute top-6 left-1/2 -translate-x-1/2 bg-gray-900 text-white px-4 py-2 rounded-full shadow-xl text-xs font-medium flex items-center gap-2 opacity-0 transition-opacity z-50 pointer-events-none">
<i data-lucide="check-circle" class="w-4 h-4 text-green-400"></i>
Copied to clipboard!
</div>
</div>
<script>
// Global Error Handler for Mobile/Preview
window.onerror = function (msg, url, line) {
const errDiv = document.createElement('div');
errDiv.style.cssText = 'position:fixed;top:0;left:0;right:0;background:red;color:white;padding:10px;z-index:9999;font-size:10px;';
errDiv.innerText = `Error: ${msg} (Line ${line})`;
document.body.appendChild(errDiv);
return false;
};
// Initialize Icons
lucide.createIcons();
let step = 0;
const chatContainer = document.getElementById('chat-container');
const input = document.getElementById('chat-input');
const quickActions = document.getElementById('quick-actions');
const sheet = document.getElementById('draft-sheet');
const sheetOverlay = document.getElementById('sheet-overlay');
const sheetContent = document.getElementById('sheet-content');
// Add ID to send button for easier targeting
const sendBtn = document.querySelector('footer div button:last-child');
// Scenarios
const userResponses = [
"Yeah... spent 4 hours on a useEffect bug. Felt stupid.",
"I guess? Just hate feeling like I'm moving backwards.",
];
const aiResponses = [
"Oof. The `useEffect` dependency array trap? It happens to the best of us. What exactly went wrong?",
"You're not moving backwards, Alex. You're deepening your mental model. A bug fixed is a lesson learned forever. Want to turn this frustration into a win?"
];
function handleInput(textarea) {
textarea.style.height = 'auto';
textarea.style.height = textarea.scrollHeight + 'px';
}
async function sendMessage() {
const text = input.value.trim();
// Handle End of Conversation
if (step >= userResponses.length && !text) {
// Shake the updated draft button to hint
quickActions.classList.add('scale-110');
setTimeout(() => quickActions.classList.remove('scale-110'), 200);
// Show toast hint
const toast = document.getElementById('toast');
toast.innerHTML = '<i data-lucide="info" class="w-4 h-4"></i> Click "Draft It" to finish!';
toast.classList.remove('opacity-0', 'bg-gray-900', 'text-white');
toast.classList.add('bg-blue-500', 'text-white', 'opacity-100');
lucide.createIcons();
setTimeout(() => toast.classList.add('opacity-0'), 2000);
return;
}
if (!text) {
// Auto-fill demo content if empty
if (step < userResponses.length) {
typeWriter(userResponses[step]);
return;
}
return;
}
// User Message
addMessage(text, 'user');
input.value = '';
input.style.height = 'auto';
// Reset Button to Loading State (Safe Replacement)
sendBtn.innerHTML = '<i data-lucide="loader" class="w-5 h-5 animate-spin"></i>';
lucide.createIcons();
await new Promise(r => setTimeout(r, 800)); // Simulate thinking
if (step === 0) {
addMessage(aiResponses[0], 'ai');
} else if (step === 1) {
addMessage(aiResponses[1], 'ai');
// Show Draft Button
setTimeout(() => {
quickActions.classList.remove('hidden');
quickActions.classList.add('flex'); // Ensure flex display
}, 500);
}
// Reset Button to Send Icon
sendBtn.innerHTML = '<i data-lucide="arrow-up" class="w-5 h-5"></i>';
// Disable if done
if (step >= 1) {
sendBtn.classList.add('opacity-50', 'cursor-not-allowed');
}
lucide.createIcons();
step++;
scrollToBottom();
}
function addMessage(text, type) {
const div = document.createElement('div');
// Ensure proper icon attributes are present before Lucide processes them
const botIcon = `<i data-lucide="bot" class="w-4 h-4"></i>`;
const userIcon = `<i data-lucide="user" class="w-4 h-4"></i>`;
div.className = `flex gap-3 max-w-[85%] message-enter ${type === 'user' ? 'ml-auto flex-row-reverse' : ''}`;
const avatar = type === 'ai'
? `<div class="w-8 h-8 bg-brand-50 rounded-full flex-shrink-0 flex items-center justify-center text-brand-500 mt-1">${botIcon}</div>`
: `<div class="w-8 h-8 bg-brand-500 rounded-full flex-shrink-0 flex items-center justify-center text-white mt-1">${userIcon}</div>`;
const bubble = type === 'ai'
? `bg-white border border-brand-100 text-brand-700`
: `bg-brand-500 text-white`;
div.innerHTML = `
${avatar}
<div class="${bubble} p-3 rounded-2xl ${type === 'ai' ? 'rounded-tl-sm' : 'rounded-tr-sm'} shadow-sm text-sm leading-relaxed">
${text}
</div>
`;
chatContainer.appendChild(div);
lucide.createIcons();
// Animate in
requestAnimationFrame(() => {
div.classList.add('message-active');
div.classList.remove('message-enter');
scrollToBottom();
});
}
function scrollToBottom() {
chatContainer.scrollTo({ top: chatContainer.scrollHeight, behavior: 'smooth' });
}
function typeWriter(text) {
input.value = text;
handleInput(input);
sendMessage();
}
// --- Sheet Logic ---
function triggerDraft() {
sheet.classList.remove('pointer-events-none');
sheetOverlay.classList.remove('opacity-0');
sheetContent.classList.remove('translate-y-full');
// Hide quick actions for cleanliness
quickActions.classList.add('hidden');
}
function closeDraft() {
sheetContent.classList.add('translate-y-full');
sheetOverlay.classList.add('opacity-0');
setTimeout(() => {
sheet.classList.add('pointer-events-none');
quickActions.classList.remove('hidden'); // Bring button back
}, 300);
}
function approveDraft() {
closeDraft();
// Show Success Toast
const toast = document.getElementById('toast');
toast.classList.remove('opacity-0', 'bg-blue-500');
toast.classList.add('bg-gray-900', 'translate-y-0', 'opacity-100');
toast.innerHTML = '<i data-lucide="check-circle" class="w-4 h-4 text-green-400"></i> Copied to clipboard!';
lucide.createIcons();
setTimeout(() => {
toast.classList.add('opacity-0');
}, 3000);
// Add system message to chat
setTimeout(() => {
const div = document.createElement('div');
div.className = "flex justify-center my-4 message-enter";
div.innerHTML = `
<div class="bg-green-50 text-green-600 px-3 py-1 rounded-full text-xs font-medium flex items-center gap-1.5 border border-green-100">
<i data-lucide="check" class="w-3 h-3"></i>
Posted to History
</div>
`;
chatContainer.appendChild(div);
lucide.createIcons();
requestAnimationFrame(() => {
div.classList.add('message-active');
div.classList.remove('message-enter');
scrollToBottom();
});
}, 500);
}
function rejectDraft() {
closeDraft();
// AI asks for feedback
setTimeout(() => {
addMessage("What should we change? Too long? Too cheesy?", 'ai');
}, 400);
}
</script>
</body>
</html>

347
_bmad-output/planning-artifacts/ux-screens-preview.html Normal file
View File

@@ -0,0 +1,347 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Test01 - App Screens Preview</title>
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://unpkg.com/lucide@latest"></script>
<link
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Merriweather:ital,wght@0,300;0,400;0,700;1,400&display=swap"
rel="stylesheet">
<style>
body {
font-family: 'Inter', sans-serif;
background-color: #0F172A;
}
.font-serif {
font-family: 'Merriweather', serif;
}
.hide-scrollbar::-webkit-scrollbar {
display: none;
}
</style>
<script>
tailwind.config = {
theme: {
extend: {
colors: {
brand: {
50: '#F1F5F9',
100: '#E2E8F0',
500: '#64748B', // Slate Blue
700: '#334155',
900: '#0F172A',
}
}
}
}
}
</script>
</head>
<body class="min-h-screen text-slate-300 p-8">
<div class="max-w-7xl mx-auto">
<header class="mb-12 text-center">
<h1 class="text-3xl font-bold text-white mb-2">Test01 App Flow</h1>
<p class="text-slate-400">Key screens for the "Guided Venting Ritual" MVP</p>
</header>
<!-- Grid of Screens -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-8 justify-items-center">
<!-- SCREEN 1: ONBOARDING / LOGIN -->
<div class="flex flex-col gap-4">
<h2 class="text-center font-medium text-white">1. The Gate (Login)</h2>
<div
class="relative w-[320px] h-[680px] bg-white rounded-[40px] shadow-2xl overflow-hidden border-8 border-slate-800 flex flex-col">
<!-- Status Bar -->
<div
class="h-6 bg-transparent flex justify-between px-5 pt-2 text-[10px] font-medium text-slate-900 z-10">
<span>9:41</span>
<div class="flex gap-1">
<i data-lucide="wifi" class="w-3 h-3"></i>
<i data-lucide="battery" class="w-3 h-3"></i>
</div>
</div>
<!-- Content -->
<div class="flex-1 flex flex-col items-center justify-center p-8 text-center relative">
<!-- BG Decoration -->
<div class="absolute top-0 left-0 w-full h-[50%] bg-brand-50 rounded-b-[60px] -z-10"></div>
<div
class="w-20 h-20 bg-brand-500 rounded-3xl flex items-center justify-center text-white mb-8 shadow-xl shadow-brand-500/20 rotate-3">
<i data-lucide="message-circle-heart" class="w-10 h-10"></i>
</div>
<h1 class="text-2xl font-bold text-slate-900 mb-2">Turn Stress into<br>Success</h1>
<p class="text-slate-500 text-sm mb-10 leading-relaxed">
Stop venting into the void. Turn your daily struggles into professional personal branding
content with one click.
</p>
<div class="w-full space-y-3">
<button
class="w-full py-3.5 bg-slate-900 text-white rounded-xl font-medium text-sm flex items-center justify-center gap-3 hover:bg-slate-800 transition">
<i data-lucide="github" class="w-4 h-4"></i>
Continue with GitHub
</button>
<button
class="w-full py-3.5 bg-white border border-slate-200 text-slate-700 rounded-xl font-medium text-sm flex items-center justify-center gap-3 hover:bg-slate-50 transition">
<svg class="w-4 h-4" viewBox="0 0 24 24">
<path
d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"
fill="#4285F4" />
<path
d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
fill="#34A853" />
<path
d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
fill="#FBBC05" />
<path
d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
fill="#EA4335" />
</svg>
Continue with Google
</button>
</div>
</div>
</div>
</div>
<!-- SCREEN 2: CHAT (Input) -->
<div class="flex flex-col gap-4">
<h2 class="text-center font-medium text-white">2. The Vent (Input)</h2>
<div
class="relative w-[320px] h-[680px] bg-[#F8FAFC] rounded-[40px] shadow-2xl overflow-hidden border-8 border-slate-800 flex flex-col">
<!-- Header -->
<div
class="h-20 bg-white/80 backdrop-blur border-b border-slate-100 flex items-end pb-3 px-5 justify-between sticky top-0 z-10">
<div class="flex items-center gap-3">
<div
class="w-8 h-8 bg-brand-100 rounded-full flex items-center justify-center text-brand-500">
<i data-lucide="bot" class="w-4 h-4"></i>
</div>
<div>
<div class="text-xs font-semibold text-slate-800">Teacher AI</div>
<div class="text-[10px] text-green-500 font-medium">Online</div>
</div>
</div>
<i data-lucide="more-horizontal" class="w-5 h-5 text-slate-400"></i>
</div>
<!-- Chat Area -->
<div class="flex-1 p-4 space-y-4 overflow-y-auto hide-scrollbar">
<!-- AI Message -->
<div class="flex gap-3">
<div
class="w-6 h-6 bg-brand-100 rounded-full flex-shrink-0 flex items-center justify-center text-brand-500 mt-1">
<i data-lucide="bot" class="w-3 h-3"></i>
</div>
<div
class="bg-white border border-slate-100 p-3 rounded-2xl rounded-tl-sm text-sm text-slate-600 shadow-sm max-w-[85%]">
Rough day? I saw you struggling with that SQL query.
</div>
</div>
<!-- User Message -->
<div class="flex gap-3 flex-row-reverse">
<div
class="w-6 h-6 bg-brand-500 rounded-full flex-shrink-0 flex items-center justify-center text-white mt-1">
<i data-lucide="user" class="w-3 h-3"></i>
</div>
<div
class="bg-brand-500 text-white p-3 rounded-2xl rounded-tr-sm text-sm shadow-sm max-w-[85%]">
It was a nightmare. I know the logic is right but the JOINs keep duplicating rows. I
felt so dumb.
</div>
</div>
<!-- AI Message -->
<div class="flex gap-3">
<div
class="w-6 h-6 bg-brand-100 rounded-full flex-shrink-0 flex items-center justify-center text-brand-500 mt-1">
<i data-lucide="bot" class="w-3 h-3"></i>
</div>
<div
class="bg-white border border-slate-100 p-3 rounded-2xl rounded-tl-sm text-sm text-slate-600 shadow-sm max-w-[85%]">
Duplication usually means a one-to-many relationship you missed. That's a classic
"gotcha," not a stupidity problem. Want me to draft a post about "Mastering the JOIN"?
</div>
</div>
<!-- Ghost Writer Prompt -->
<div class="flex justify-center py-2">
<button
class="bg-brand-500 text-white text-xs font-medium px-4 py-2 rounded-full shadow-lg shadow-brand-500/20 flex items-center gap-2 animate-bounce">
<i data-lucide="sparkles" class="w-3 h-3"></i>
Draft It
</button>
</div>
</div>
<!-- Input -->
<div class="h-16 bg-white border-t border-slate-100 px-4 flex items-center gap-2">
<button class="p-2 text-slate-400"><i data-lucide="plus" class="w-5 h-5"></i></button>
<div class="flex-1 h-9 bg-slate-50 rounded-full flex items-center px-3 text-sm text-slate-400">
Reply...</div>
<button class="p-2 text-brand-500"><i data-lucide="send" class="w-5 h-5"></i></button>
</div>
</div>
</div>
<!-- SCREEN 3: RESULT (The Draft) -->
<div class="flex flex-col gap-4">
<h2 class="text-center font-medium text-white">3. The Magic (Result)</h2>
<div
class="relative w-[320px] h-[680px] bg-slate-800 rounded-[40px] shadow-2xl overflow-hidden border-8 border-slate-800 flex flex-col">
<!-- Overlay Background (Simulating Sheet open over chat) -->
<div class="absolute inset-x-0 top-0 h-20 bg-slate-900/50 z-0"></div>
<!-- The Sheet -->
<div class="flex-1 mt-10 bg-white rounded-t-3xl overflow-hidden flex flex-col z-10 relative">
<!-- Handle -->
<div class="w-12 h-1 bg-slate-200 rounded-full mx-auto mt-3 mb-4"></div>
<!-- Content -->
<div class="flex-1 overflow-y-scroll px-6 pb-24 hide-scrollbar">
<div
class="flex items-center gap-2 text-brand-500 bg-brand-50 w-max px-3 py-1 rounded-full text-[10px] font-bold uppercase tracking-wider mb-4">
Ghostwriter Draft
</div>
<h2 class="text-xl font-bold text-slate-900 font-sans leading-tight mb-4">
SQL JOINs: Why 1+1 Sometimes Equals 4 (And How to Fix It)
</h2>
<div class="flex items-center gap-2 mb-6">
<div class="h-px bg-gray-100 flex-1"></div>
<span class="text-[10px] text-gray-400 uppercase tracking-wider">Created just now</span>
<div class="h-px bg-gray-100 flex-1"></div>
</div>
<p class="font-serif text-slate-600 text-sm leading-7 mb-4">
today I spent 2 hours staring at a dataset that doubled in size every time I ran a
query. I thought I was bad at math. Turns out, I was just bad at JOINs.
</p>
<p class="font-serif text-slate-600 text-sm leading-7 mb-4">
I learned the hard way: if you JOIN a table with duplicates, you don't just "add"
data—you multiply it. This is why understanding your primary keys matters more than
writing complex logic.
</p>
<p class="font-serif text-slate-600 text-sm leading-7">
Data isn't just numbers; it's relationships. And today, I finally understood this one.
💡
<br><br>
#DataAnalytics #SQL #LearningJourney #Tech
</p>
</div>
<!-- Sticky Actions -->
<div
class="absolute bottom-0 w-full p-4 bg-white/95 backdrop-blur border-t border-slate-100 flex gap-3">
<button
class="flex-1 py-3 border border-slate-200 rounded-xl text-slate-500 text-sm font-medium flex items-center justify-center gap-2">
<i data-lucide="thumbs-down" class="w-4 h-4"></i>
Fix
</button>
<button
class="flex-[2] py-3 bg-brand-500 rounded-xl text-white text-sm font-medium flex items-center justify-center gap-2 shadow-lg shadow-brand-500/25">
<i data-lucide="thumbs-up" class="w-4 h-4"></i>
Approve & Copy
</button>
</div>
</div>
</div>
</div>
<!-- SCREEN 4: HISTORY -->
<div class="flex flex-col gap-4">
<h2 class="text-center font-medium text-white">4. Reflection (History)</h2>
<div
class="relative w-[320px] h-[680px] bg-[#F8FAFC] rounded-[40px] shadow-2xl overflow-hidden border-8 border-slate-800 flex flex-col">
<!-- Header -->
<div class="h-24 bg-white px-6 pt-10 pb-4 flex justify-between items-end border-b border-slate-100">
<h1 class="text-2xl font-bold text-slate-900">History</h1>
<div class="w-8 h-8 rounded-full bg-slate-100 border border-white shadow-sm overflow-hidden">
<div class="w-full h-full flex items-center justify-center bg-brand-500 text-white text-xs">
MA</div>
</div>
</div>
<!-- List -->
<div class="flex-1 overflow-y-auto p-4 space-y-3 hide-scrollbar">
<!-- Item 1 -->
<div
class="bg-white p-4 rounded-2xl shadow-sm border border-slate-100/50 relative overflow-hidden group">
<div class="absolute left-0 top-0 bottom-0 w-1 bg-brand-500"></div>
<div class="flex justify-between items-start mb-2">
<h3 class="font-bold text-slate-800 text-sm">SQL JOINs: Why 1+1...</h3>
<span
class="text-[10px] text-slate-400 bg-slate-50 px-2 py-0.5 rounded-full">Today</span>
</div>
<p class="text-xs text-slate-500 line-clamp-2 leading-relaxed mb-3">
Today I spent 2 hours staring at a dataset that doubled in size every time I ran a
query. I thought I was bad at math...
</p>
<div class="flex gap-2">
<button
class="flex-1 bg-slate-50 hover:bg-slate-100 text-slate-600 text-[10px] font-medium py-1.5 rounded-lg transition">View</button>
<button
class="flex-1 bg-brand-50 hover:bg-brand-100 text-brand-600 text-[10px] font-medium py-1.5 rounded-lg transition flex items-center justify-center gap-1">
<i data-lucide="copy" class="w-3 h-3"></i> Copy
</button>
</div>
</div>
<!-- Item 2 -->
<div
class="bg-white p-4 rounded-2xl shadow-sm border border-slate-100/50 relative overflow-hidden opacity-70">
<div class="absolute left-0 top-0 bottom-0 w-1 bg-gray-300"></div>
<div class="flex justify-between items-start mb-2">
<h3 class="font-bold text-slate-800 text-sm">Python Indentation...</h3>
<span
class="text-[10px] text-slate-400 bg-slate-50 px-2 py-0.5 rounded-full">Yesterday</span>
</div>
<p class="text-xs text-slate-500 line-clamp-2 leading-relaxed">
Python whitespace drove me crazy today. Why does an invisible character break my entire
script? Here is what I learned...
</p>
</div>
</div>
<!-- Bottom Nav -->
<div class="h-16 bg-white border-t border-slate-100 flex justify-around items-center px-2">
<button class="p-2 flex flex-col items-center gap-1 text-slate-400 hover:text-brand-500">
<i data-lucide="message-square" class="w-5 h-5"></i>
<span class="text-[10px] font-medium">Vent</span>
</button>
<button class="p-2 flex flex-col items-center gap-1 text-brand-500">
<i data-lucide="book-open" class="w-5 h-5"></i>
<span class="text-[10px] font-medium">History</span>
</button>
<button class="p-2 flex flex-col items-center gap-1 text-slate-400 hover:text-brand-500">
<i data-lucide="user" class="w-5 h-5"></i>
<span class="text-[10px] font-medium">Profile</span>
</button>
</div>
</div>
</div>
</div>
</div>
<script>
lucide.createIcons();
</script>
</body>
</html>

17
_bmad-output/planning-artifacts/ux_brainstorm_notes.md Normal file
View File

@@ -0,0 +1,17 @@
# UX Brainstorming Notes
**Date:** 2026-01-20
**Context:** Pre-PRD Brainstorming
## Core Interaction
- **Chat Interface:** "WhatsApp-style" chat. Familiar, fast, low friction.
- **Input Method:** Mobile-first text entry (likely voice later, but text focus now).
## The "Magic Moment" (Review)
- **Layout:** Side-by-side view.
- **Interaction:** User sees raw "vent" on one side (or top) and "generated post" on the other.
- **Comparison:** Easy to see the transformation from "messy thought" to "polished content".
## Visual Vibe & Aesthetics
- **Platform:** Mobile-first, but must be responsive for PC display.
- **Style:** "Gamified but with more pastel colors."
- **Tone:** Friendly, approachable, not "hacker/terminal" dark mode. Soft, encouraging.

452
_bmad-output/planning-artifacts/validation-report-Test01-2026-01-23.md Normal file
View File

@@ -0,0 +1,452 @@
---
validationTarget: '/home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/prd.md'
validationDate: '2026-01-23'
inputDocuments:
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux_brainstorm_notes.md
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
- /home/maximilienmao/Projects/Test01/_bmad-output/analysis/brainstorming-session-2026-01-20.md
validationStepsCompleted: ['step-v-01-discovery', 'step-v-02-format-detection', 'step-v-03-density-validation', 'step-v-04-brief-coverage-validation', 'step-v-05-measurability-validation', 'step-v-06-traceability-validation', 'step-v-07-implementation-leakage-validation', 'step-v-08-domain-compliance-validation', 'step-v-09-project-type-validation', 'step-v-10-smart-validation', 'step-v-11-holistic-quality-validation', 'step-v-12-completeness-validation']
validationStatus: COMPLETE
holisticQualityRating: '5/5'
overallStatus: 'Pass'
---
# PRD Validation Report
**PRD Being Validated:** /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/prd.md
**Validation Date:** 2026-01-23
## Input Documents
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux_brainstorm_notes.md
- /home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
- /home/maximilienmao/Projects/Test01/_bmad-output/analysis/brainstorming-session-2026-01-20.md
## Validation Findings
[Findings will be appended as validation progresses]
## Format Detection
**PRD Structure:**
## Executive Summary
## Success Criteria
## Product Scope & Phased Development
## User Journeys
## Domain-Specific Requirements
## Innovation & Novel Patterns
## Web App Specific Requirements
## Functional Requirements
## Non-Functional Requirements
**BMAD Core Sections Present:**
- Executive Summary: Present
- Success Criteria: Present
- Product Scope: Present
- User Journeys: Present
- Functional Requirements: Present
- Non-Functional Requirements: Present
**Format Classification:** BMAD Standard
**Core Sections Present:** 6/6
## Information Density Validation
**Anti-Pattern Violations:**
**Conversational Filler:** 0 occurrences
**Wordy Phrases:** 0 occurrences
**Redundant Phrases:** 0 occurrences
**Total Violations:** 0
**Severity Assessment:** Pass
**Recommendation:**
PRD demonstrates good information density with minimal violations.
## Product Brief Coverage
**Product Brief:** product-brief-Test01-2026-01-20.md
### Coverage Map
**Vision Statement:** Fully Covered
(Executive Summary & Journey 1 match the dual-agent vision)
**Target Users:** Fully Covered
(Primary User 'Alex - The Exhausted Learner' and Secondary User 'Sarah - The Hiring Manager' are explicitly included)
**Problem Statement:** Fully Covered
(Implicit in 'Core Innovation' and 'Key Value' - turning struggle into insight)
**Key Features:** Fully Covered
(Chat Interface, Teacher/Ghostwriter Agents, Copy Export, Draft View - all present in Functional Requirements)
**Goals/Objectives:** Fully Covered
(Engagement lift, Consistency, Low Edit Distance - mapped to Success Criteria)
**Differentiators:** Fully Covered
(Vlog-style authenticity and Two-Stage Pipeline explicitly mentioned)
### Coverage Summary
**Overall Coverage:** 100%
**Critical Gaps:** 0
**Moderate Gaps:** 0
**Informational Gaps:** 0
**Recommendation:**
PRD provides excellent coverage of Product Brief content.
## Measurability Validation
### Functional Requirements
**Total FRs Analyzed:** 27
**Format Violations:** 0
**Subjective Adjectives Found:** 0
(Matches found in 'MVP Strategy' and 'SEO Strategy' sections, but these contain context or are not strictly requirements. The FRs themselves are clean.)
**Vague Quantifiers Found:** 0
**Implementation Leakage:** 0
**FR Violations Total:** 0
### Non-Functional Requirements
**Total NFRs Analyzed:** 8
**Missing Metrics:** 0
**Incomplete Template:** 0
**Missing Context:** 0
**NFR Violations Total:** 0
### Overall Assessment
**Total Requirements:** 35
**Total Violations:** 0
**Severity:** Pass
**Recommendation:**
Requirements demonstrate good measurability with minimal issues. The matches for subjective terms ('faster', 'fast') were in descriptive sections (MVP Philosophy, SEO), not in the Requirements definitions themselves, so they are not violations.
## Traceability Validation
### Chain Validation
**Executive Summary → Success Criteria:** Intact
(Vision aligned with User Success metrics)
**Success Criteria → User Journeys:** Intact
(Consistent posting journey supported by Journey 1; Refinement supported by Journey 2)
**User Journeys → Functional Requirements:** Intact
- Journey 1 (Legacy Log) -> FR-01, FR-02, FR-03, FR-06
- Journey 2 (Refinement) -> FR-01, FR-02, FR-03 (Teacher interaction)
- Journey 3 (Recruiter) -> Impact of FR-03 (Quality)
- Journey 4 (Power User) -> FR-15, FR-16, FR-17, FR-18, FR-19 (New Config FRs)
**Scope → FR Alignment:** Intact
- Must-Have Capabilities (Chat, Offline, Dual-Agent, Export, History, Settings) fully mapped to FRs.
### Orphan Elements
**Orphan Functional Requirements:** 0
**Unsupported Success Criteria:** 0
**User Journeys Without FRs:** 0
### Traceability Matrix
All requirements trace back to defined User Journeys or MVP Scope items.
New BYOD requirements (FR-15 to FR-19) are correctly traced to the new 'Power User' Journey 4 and Scope items.
**Total Traceability Issues:** 0
**Severity:** Pass
**Recommendation:**
Traceability chain is intact - all requirements trace to user needs or business objectives.
## Implementation Leakage Validation
### Leakage by Category
**Frontend Frameworks:** 0 violations
**Backend Frameworks:** 0 violations
**Databases:** 0 violations
**Cloud Platforms:** 0 violations
**Infrastructure:** 0 violations
**Libraries:** 0 violations
**Other Implementation Details:** 0 violations
(Note: 'JSON/Markdown' in FR-14 is a user-facing export format capability, not an internal implementation detail, so it is allowed.)
### Summary
**Total Implementation Leakage Violations:** 0
**Severity:** Pass
**Recommendation:**
No significant implementation leakage found. Requirements properly specify WHAT without HOW.
## Domain Compliance Validation
**Domain:** edtech
**Complexity:** Medium
### Required Special Sections
**privacy_compliance (COPPA/FERPA):** Present
(PRD Section 'Compliance & Regulatory' > 'Data Privacy (Adult Learners)' addresses strict control, 'Private by Default')
**content_guidelines (Moderation):** Present
(PRD Section 'Compliance & Regulatory' > 'Content Moderation')
**accessibility_features (WCAG):** Present
(PRD Section 'Accessibility' > 'WCAG 2.1 AA' and NFR-07)
**curriculum_alignment (Bloom's Taxonomy):** Present
(PRD Section 'Educational Framework Alignment' > 'Bloom's Taxonomy Application')
### Compliance Matrix
| Requirement | Status | Notes |
| ------------------ | ------ | ----------------------------------------------------------------------------------------------- |
| Student Privacy | Met | Addressed as 'Adult Learners' (no children targeting implicity, but privacy safeguards engaged) |
| Content Moderation | Met | Reputation safety guardrails included |
| Accessibility | Met | WCAG 2.1 AA explicitly cited |
| Learning Framework | Met | Bloom's Taxonomy explicitly applied |
### Summary
**Required Sections Present:** 4/4
**Compliance Gaps:** 0
**Severity:** Pass
**Recommendation:**
All required domain compliance sections are present and adequately documented for an EdTech product.
## Project-Type Compliance Validation
**Project Type:** web_app (PWA Variant)
### Required Sections
**browser_matrix:** Present
(Addressed in 'Browser Support Matrix' under 'Web App Specific Requirements')
**responsive_design:** Present
(Addressed in 'Responsive Design Targets' under 'Web App Specific Requirements')
**performance_targets:** Present
(Addressed in NFR-02 App Load Time and NFR-01 Chat Latency)
**seo_strategy:** Present
(Addressed in 'SEO Strategy' under 'Web App Specific Requirements')
**accessibility_level:** Present
(Addressed in 'Accessibility' section and WCAG reference)
### Excluded Sections (Should Not Be Present)
**native_features:** Absent
(Correctly abstracted to PWA capabilities only, no native Swift/Kotlin)
**cli_commands:** Absent
### Compliance Summary
**Required Sections:** 5/5 present
**Excluded Sections Present:** 0
**Compliance Score:** 100%
**Severity:** Pass
**Recommendation:**
All required sections for web_app (PWA) are present. No excluded sections found.
## SMART Requirements Validation
**Total Functional Requirements:** 19
### Scoring Summary
**All scores ≥ 3:** 100% (19/19)
**All scores ≥ 4:** 100% (19/19)
**Overall Average Score:** 5.0/5.0
### Scoring Table
| FR # | Specific | Measurable | Attainable | Relevant | Traceable | Average | Flag |
| ----- | -------- | ---------- | ---------- | -------- | --------- | ------- | ---- |
| FR-01 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-02 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-03 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-04 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-05 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-06 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-07 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-08 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-09 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-10 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-11 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-12 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-13 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-14 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-15 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-16 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-17 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-18 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
| FR-19 | 5 | 5 | 5 | 5 | 5 | 5.0 | - |
**Legend:** 1=Poor, 3=Acceptable, 5=Excellent
**Flag:** X = Score < 3 in one or more categories
### Overall Assessment
**Severity:** Pass
**Recommendation:**
Functional Requirements demonstrate excellent SMART quality. All FRs are specific, testable, and aligned with user needs.
## Holistic Quality Assessment
### Document Flow & Coherence
**Assessment:** Excellent
**Strengths:**
- Strong narrative arc from "Vent" to "Lightbulb Moment" in Executive Summary and User Journeys.
- Clean transition from high-level Vision ("Legacy Log") to granular Functional Requirements.
- Consistent terminology ("Teacher", "Ghostwriter", "Legacy Log") used throughout all sections.
**Areas for Improvement:**
- Ensure 'Innovation Analysis' and 'Domain Requirements' are integrated smoothly for readers less familiar with BMAD structure (though structure itself is correct).
### Dual Audience Effectiveness
**For Humans:**
- Executive-friendly: Excellent. Vision and Differentiators are upfront and punchy.
- Developer clarity: Excellent. FRs are specific and implementation-agnostic.
- Designer clarity: Excellent. Journeys paint a vivid picture of the interaction model.
- Stakeholder decision-making: Strong. Success metrics and MVP scope are clear.
**For LLMs:**
- Machine-readable structure: Excellent. Consistent Markdown headers and lists.
- UX readiness: High. Journeys map directly to required screens/flows.
- Architecture readiness: High. NFRs and PWA constraints provide clear architectural boundaries.
- Epic/Story readiness: High. FRs are atomic enough to become User Stories.
**Dual Audience Score:** 5/5
### BMAD PRD Principles Compliance
| Principle | Status | Notes |
| ------------------- | ------ | -------------------------------------------------------------- |
| Information Density | Met | Concise, punchy sentences. |
| Measurability | Met | Success criteria and NFRs have specific metrics. |
| Traceability | Met | Clear lineage from Vision to FRs. |
| Domain Awareness | Met | EdTech specific constraints (Adult Learners, Privacy) handled. |
| Zero Anti-Patterns | Met | No filler found in density check. |
| Dual Audience | Met | Structured Headers + Human narrative. |
| Markdown Format | Met | Standard GFM used effectively. |
**Principles Met:** 7/7
### Overall Quality Rating
**Rating:** 5/5 - Excellent
**Scale:**
- 5/5 - Excellent: Exemplary, ready for production use
- 4/5 - Good: Strong with minor improvements needed
- 3/5 - Adequate: Acceptable but needs refinement
- 2/5 - Needs Work: Significant gaps or issues
- 1/5 - Problematic: Major flaws, needs substantial revision
### Top 3 Improvements
1. **Enhance Innovation Analysis:** While present, expanding on *why* the 'Teacher' agent is better than standard ChatGPT prompting could deeper solidify the value prop for investors.
2. **Explicit Data Schema:** Adding a high-level Data Entity Model (e.g., User, ChatSession, Artifact) in a Technical Appendix could further aid the Architecture step (though strictly optional for PRD).
3. **Visual Journey Map:** Including a Mermaid diagram for the "Vent -> Insight" flow would visually reinforce the core loop for design teams.
### Summary
**This PRD is:** An excellent, high-density specification that clearly articulates a novel EdTech product with robust technical and domain constraints.
**To make it great:** It is already great. Focus on the visual journey map to help the UX team visualize the 'Teacher' interaction flow.
## Completeness Validation
### Template Completeness
**Template Variables Found:** 0
(No template placeholders like {TBD} or [TODO] found)
### Content Completeness by Section
**Executive Summary:** Complete
(Vision, Innovation, Differentiators present)
**Success Criteria:** Complete
(User, Business, Technical metrics present)
**Product Scope:** Complete
(MVP, Phases, Risks present)
**User Journeys:** Complete
(4 distinct journeys present)
**Functional Requirements:** Complete
(Start at FR-01, ends at FR-19)
**Non-Functional Requirements:** Complete
(Start at NFR-01, ends at NFR-07)
### Section-Specific Completeness
**Success Criteria Measurability:** All measurable (as per Step 10)
**User Journeys Coverage:** Yes - covers Primary, Secondary, Power users
**FRs Cover MVP Scope:** Yes - fully mapped (as per Step 6)
**NFRs Have Specific Criteria:** All specific (as per Step 5)
### Frontmatter Completeness
**stepsCompleted:** Present
**classification:** Present
**inputDocuments:** Present
**date:** Present (in editHistory)
**Frontmatter Completeness:** 4/4
### Completeness Summary
**Overall Completeness:** 100% (6/6 sections)
**Critical Gaps:** 0
**Minor Gaps:** 0
**Severity:** Pass
**Recommendation:**
PRD is complete with all required sections and content present.