[Phase 3] PRD View - Document Creation & Discovery

[frankbria]

Overview

Implement the PRD View for creating, viewing, and iterating on Product Requirements Documents with AI-powered Socratic discovery.

Reference: docs/PHASE_3_UI_ARCHITECTURE.md Section 1.2, 3.2, 5.1

Purpose

Create, view, and iterate on Product Requirements Documents.

User Actions

• Upload/paste PRD markdown
• Start discovery session (Socratic AI conversation)
• Edit PRD content
• Generate tasks from PRD

Components

PRDView
├── PRDHeader
│   ├── PRDTitle (editable inline)
│   ├── PRDActions
│   │   ├── UploadPRDButton
│   │   ├── StartDiscoveryButton
│   │   └── GenerateTasksButton
│   └── PRDMetadata (version, file path)
├── PRDContent (two-column when discovery active)
│   ├── MarkdownEditor (left, or full-width when no discovery)
│   └── DiscoveryPanel (right, collapsible)
│       ├── DiscoveryTranscript (chat-style messages)
│       └── DiscoveryInput (text input + send button)
└── AssociatedTasksSummary
    └── TaskCountByStatus (compact badges)

API Endpoints Used

• GET /api/v2/prd - Get current PRD
• POST /api/v2/prd - Create/update PRD
• POST /api/v2/discovery/start - Start discovery session
• POST /api/v2/discovery/respond - Send discovery response
• POST /api/v2/tasks/generate - Generate tasks from PRD

Acceptance Criteria

• Upload PRD via file picker or paste markdown
• Markdown editor with live preview
• Start discovery session button launches chat panel
• Chat-style discovery with AI avatar/branding
• Thinking indicator while AI generates responses
• Discovery panel slides in from right
• "Skip discovery" option to write PRD manually
• Generate tasks button (enabled when PRD exists)
• Shows associated task counts by status
• Responsive two-column layout during discovery

Route

• /prd - PRD editor
• /prd/discovery - Discovery session sub-view

Real-time Requirements

• SSE for discovery session responses (streaming AI replies)

[traycerai]

Plan

Observations

The codebase has a well-structured Phase 3 architecture with:

• Backend APIs: Complete v2 endpoints for PRD (file:codeframe/ui/routers/prd_v2.py), discovery (file:codeframe/ui/routers/discovery_v2.py), and tasks (file:codeframe/ui/routers/tasks_v2.py)
• Frontend Stack: Next.js 14 with App Router, React 18, Shadcn/UI components, Tailwind CSS, and Hugeicons
• Existing Patterns: Legacy components (file:legacy/web-ui/src/components/PRDModal.tsx, file:legacy/web-ui/src/components/DiscoveryProgress.tsx) provide reference implementations but need rebuilding per Phase 3 spec
• Streaming Infrastructure: SSE support via file:codeframe/core/streaming.py with EventPublisher for real-time updates
• Type System: Comprehensive TypeScript types in file:legacy/web-ui/src/types/

Approach

Following the Phase 3 UI Architecture (file:docs/PHASE_3_UI_ARCHITECTURE.md Section 3.2), implement the PRD View as a standalone route with integrated discovery session support. The approach prioritizes:

1. Component-first development: Build reusable UI components matching the architecture's component hierarchy
2. API integration: Connect to existing v2 endpoints without backend changes
3. Real-time streaming: Implement SSE for discovery chat responses
4. Progressive enhancement: Start with core functionality (upload/edit PRD), then add discovery, then task generation

This aligns with the "golden path" philosophy—building only what's necessary for the core workflow.

Implementation Steps

1. Create Route Structure

Create PRD route pages:

• Create file:legacy/web-ui/src/app/prd/page.tsx for main PRD editor view
• Create file:legacy/web-ui/src/app/prd/discovery/page.tsx for discovery session sub-view (optional, can be handled in main view with state)

Update Navigation:

• Modify file:legacy/web-ui/src/components/Navigation.tsx to add PRD navigation link (document icon)
• Add route to sidebar navigation per architecture Section 2

2. Define TypeScript Types

Create PRD-specific types:

• Create file:legacy/web-ui/src/types/prd.ts with interfaces:
  • PrdRecord (id, workspace_id, title, content, metadata, created_at, version, parent_id, change_summary, chain_id)
  • DiscoverySession (session_id, state, question, answered_count, is_complete)
  • DiscoveryMessage (role: 'user' | 'assistant', content, timestamp)
  • TaskGenerationResult (task_count, tasks)

Update API client:

• Extend file:legacy/web-ui/src/lib/api.ts with prdV2Api object containing:
  • getLatest() → GET /api/v2/prd/latest
  • create(content, title?) → POST /api/v2/prd
  • update(prdId, content) → POST /api/v2/prd/{id}/versions
  • startDiscovery() → POST /api/v2/discovery/start
  • submitAnswer(sessionId, answer) → POST /api/v2/discovery/{session_id}/answer
  • generatePrd(sessionId) → POST /api/v2/discovery/{session_id}/generate-prd
  • generateTasks(prdId?) → POST /api/v2/discovery/generate-tasks

3. Build Core Components

Component hierarchy per architecture Section 3.2:

PRDView (Main Container)

• Create file:legacy/web-ui/src/components/prd/PRDView.tsx
• State management: PRD content, discovery session, task summary
• Layout: Responsive grid (single column default, two-column when discovery active)
• Integrate all child components

PRDHeader

• Create file:legacy/web-ui/src/components/prd/PRDHeader.tsx
• Components:
  • PRDTitle: Inline editable title (contentEditable or input field)
  • PRDActions: Button group with Upload, Start Discovery, Generate Tasks
  • PRDMetadata: Display version, file path, timestamps
• Use Shadcn Button, Input components

PRDContent

• Create file:legacy/web-ui/src/components/prd/PRDContent.tsx
• Two-column layout using CSS Grid or Flexbox
• Left pane: MarkdownEditor (full-width when discovery inactive)
• Right pane: DiscoveryPanel (collapsible, slides in from right)

MarkdownEditor

• Create file:legacy/web-ui/src/components/prd/MarkdownEditor.tsx
• Use react-markdown (already in dependencies) for live preview
• Split view: Textarea for editing + rendered preview
• Debounced auto-save to prevent excessive API calls
• Syntax highlighting for code blocks via Shiki (mentioned in architecture)

DiscoveryPanel

• Create file:legacy/web-ui/src/components/prd/DiscoveryPanel.tsx
• Collapsible panel with slide-in animation (Tailwind transitions)
• Contains DiscoveryTranscript and DiscoveryInput
• Close button to collapse panel

DiscoveryTranscript

• Create file:legacy/web-ui/src/components/prd/DiscoveryTranscript.tsx
• Chat-style message list (similar to file:legacy/web-ui/src/components/ChatInterface.tsx)
• Message bubbles: User (right-aligned, primary color) vs AI (left-aligned, muted)
• AI avatar/branding icon (use Hugeicons)
• Auto-scroll to bottom on new messages
• Thinking indicator: Animated dots while AI generates response

DiscoveryInput

• Create file:legacy/web-ui/src/components/prd/DiscoveryInput.tsx
• Textarea with send button
• Character count indicator (max 10,000 per API)
• Keyboard shortcut: Ctrl+Enter to submit
• Disabled state while waiting for AI response

AssociatedTasksSummary

• Create file:legacy/web-ui/src/components/prd/AssociatedTasksSummary.tsx
• Compact badge display showing task counts by status
• Use Shadcn Badge component
• Format: "READY: 5 | IN_PROGRESS: 2 | DONE: 8"
• Click to navigate to /tasks view (future enhancement)

4. Implement Upload/Paste PRD Flow

UploadPRDModal:

• Create file:legacy/web-ui/src/components/prd/UploadPRDModal.tsx
• Shadcn Dialog component
• Two tabs: File Upload | Paste Markdown
• File upload: Accept .md files, read content via FileReader API
• Paste: Textarea for direct markdown input
• Validation: Check content length, markdown format
• On submit: Call prdV2Api.create(), update PRDView state

5. Implement Discovery Session Flow

State management in PRDView:

• Track discovery session state: idle | discovering | completed
• Store session_id, messages array, current question
• Use SWR for polling discovery status (optional, prefer SSE)

Start Discovery:

• Button click → Call prdV2Api.startDiscovery()
• Response contains session_id and first question
• Slide in DiscoveryPanel from right (CSS transform transition)
• Display first question in DiscoveryTranscript

Answer Submission:

• User types answer → Click send or Ctrl+Enter
• Show thinking indicator (animated dots)
• Call prdV2Api.submitAnswer(sessionId, answer)
• Response contains:
  • accepted: boolean (if false, show feedback)
  • next_question: Next question or null if complete
  • is_complete: boolean
• Append user message and AI response to transcript
• If complete, show "Generate PRD" button

SSE Streaming (Optional Enhancement):

• For streaming AI responses, implement SSE client
• Connect to /api/v2/discovery/{session_id}/stream (if endpoint exists)
• Display partial responses as they arrive (typewriter effect)

6. Implement PRD Generation from Discovery

Generate PRD Button:

• Enabled when discovery session is complete
• Click → Call prdV2Api.generatePrd(sessionId)
• Show loading spinner with progress message
• Response contains prd_id, title, preview
• Fetch full PRD via prdV2Api.getLatest()
• Populate MarkdownEditor with generated content
• Collapse DiscoveryPanel, show success toast

Skip Discovery Option:

• "Skip Discovery" button in DiscoveryPanel header
• Closes panel, allows manual PRD writing
• User can start discovery later if needed

7. Implement Task Generation

Generate Tasks Button:

• Located in PRDHeader actions
• Enabled when PRD exists (content not empty)
• Click → Call prdV2Api.generateTasks()
• Show loading modal with progress indicator
• Response contains task_count and task list
• Update AssociatedTasksSummary with counts
• Show success toast: "Generated X tasks"
• Optionally navigate to /tasks view

8. Add Real-time Updates

SSE Integration for Discovery:

• Create file:legacy/web-ui/src/hooks/useDiscoveryStream.ts custom hook
• Connect to SSE endpoint when discovery session active
• Listen for events:
  • discovery_question_ready: New question available
  • discovery_completed: Session finished
  • prd_generation_started: PRD generation began
  • prd_generation_completed: PRD ready
• Update component state based on events

WebSocket Integration (Alternative):

• Reuse existing WebSocket client from file:legacy/web-ui/src/lib/websocket.ts
• Subscribe to discovery events for project
• Handle same event types as SSE

9. Styling and Responsiveness

Tailwind CSS Classes:

• Use existing Shadcn/UI theme variables (bg-card, text-foreground, border-border)
• Two-column layout: grid grid-cols-1 lg:grid-cols-2 gap-4
• Discovery panel slide-in: transform transition-transform duration-300 translate-x-0 lg:translate-x-full
• Markdown preview: prose prose-sm max-w-none (Tailwind Typography)

Mobile Responsiveness:

• Stack columns vertically on mobile
• Discovery panel becomes full-screen overlay on small screens
• Collapsible sections for better mobile UX

10. Error Handling and Loading States

Error Boundaries:

• Wrap PRDView in ErrorBoundary component
• Display user-friendly error messages for API failures
• Retry buttons for transient errors

Loading States:

• Skeleton loaders for PRD content while fetching
• Spinner for discovery answer submission
• Progress bar for PRD/task generation
• Disabled states for buttons during operations

Validation:

• Client-side validation for answer length (1-10,000 chars)
• Markdown syntax validation (optional, warn on invalid syntax)
• Prevent duplicate submissions (debounce, disable button)

11. Testing Considerations

Component Tests:

• Test PRDView rendering with different states (idle, discovering, completed)
• Test MarkdownEditor editing and preview
• Test DiscoveryPanel message display and submission
• Mock API calls using MSW (already in dependencies)

Integration Tests:

• Test full discovery flow: start → answer questions → generate PRD
• Test upload PRD flow
• Test task generation from PRD

E2E Tests (Future):

• Full user journey from discovery to task generation

12. Documentation

Update Architecture Docs:

• Document component structure in file:docs/PHASE_3_UI_ARCHITECTURE.md
• Add screenshots/wireframes to docs

Code Comments:

• JSDoc comments for all components and functions
• Inline comments for complex logic (SSE handling, state management)

README Updates:

• Add PRD View to feature list
• Document discovery workflow for users

---

Component Dependency Graph

graph TD
    A[PRDView] --> B[PRDHeader]
    A --> C[PRDContent]
    A --> D[AssociatedTasksSummary]
    
    B --> E[PRDTitle]
    B --> F[PRDActions]
    B --> G[PRDMetadata]
    
    F --> H[UploadPRDButton]
    F --> I[StartDiscoveryButton]
    F --> J[GenerateTasksButton]
    
    C --> K[MarkdownEditor]
    C --> L[DiscoveryPanel]
    
    L --> M[DiscoveryTranscript]
    L --> N[DiscoveryInput]
    
    H --> O[UploadPRDModal]
    
    style A fill:#e1f5ff
    style C fill:#fff4e1
    style L fill:#ffe1f5

Loading

Discovery Session Flow

sequenceDiagram
    participant User
    participant PRDView
    participant API
    participant AI
    
    User->>PRDView: Click "Start Discovery"
    PRDView->>API: POST /api/v2/discovery/start
    API->>AI: Initialize session
    AI-->>API: First question
    API-->>PRDView: {session_id, question}
    PRDView->>PRDView: Show DiscoveryPanel
    
    loop Answer Questions
        User->>PRDView: Type answer + submit
        PRDView->>API: POST /api/v2/discovery/{id}/answer
        API->>AI: Validate & process answer
        AI-->>API: Next question or completion
        API-->>PRDView: {accepted, next_question, is_complete}
        PRDView->>PRDView: Update transcript
    end
    
    User->>PRDView: Click "Generate PRD"
    PRDView->>API: POST /api/v2/discovery/{id}/generate-prd
    API->>AI: Synthesize PRD from answers
    AI-->>API: Generated PRD content
    API-->>PRDView: {prd_id, title, content}
    PRDView->>PRDView: Populate MarkdownEditor
    PRDView->>PRDView: Collapse DiscoveryPanel

Loading

File Structure

legacy/web-ui/src/
├── app/
│   └── prd/
│       ├── page.tsx                    # Main PRD route
│       └── discovery/
│           └── page.tsx                # Discovery sub-route (optional)
├── components/
│   ├── Navigation.tsx                  # Update with PRD link
│   └── prd/
│       ├── PRDView.tsx                 # Main container
│       ├── PRDHeader.tsx               # Header with actions
│       ├── PRDContent.tsx              # Two-column layout
│       ├── MarkdownEditor.tsx          # Editor + preview
│       ├── DiscoveryPanel.tsx          # Collapsible chat panel
│       ├── DiscoveryTranscript.tsx     # Message list
│       ├── DiscoveryInput.tsx          # Answer input
│       ├── AssociatedTasksSummary.tsx  # Task count badges
│       └── UploadPRDModal.tsx          # Upload/paste modal
├── hooks/
│   └── useDiscoveryStream.ts           # SSE hook for discovery
├── lib/
│   └── api.ts                          # Add prdV2Api methods
└── types/
    └── prd.ts                          # PRD-specific types

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-structured Phase 3 architecture with:
- **Backend APIs**: Complete v2 endpoints for PRD (`file:codeframe/ui/routers/prd_v2.py`), discovery (`file:codeframe/ui/routers/discovery_v2.py`), and tasks (`file:codeframe/ui/routers/tasks_v2.py`)
- **Frontend Stack**: Next.js 14 with App Router, React 18, Shadcn/UI components, Tailwind CSS, and Hugeicons
- **Existing Patterns**: Legacy components (`file:legacy/web-ui/src/components/PRDModal.tsx`, `file:legacy/web-ui/src/components/DiscoveryProgress.tsx`) provide reference implementations but need rebuilding per Phase 3 spec
- **Streaming Infrastructure**: SSE support via `file:codeframe/core/streaming.py` with EventPublisher for real-time updates
- **Type System**: Comprehensive TypeScript types in `file:legacy/web-ui/src/types/`

## Approach

Following the **Phase 3 UI Architecture** (`file:docs/PHASE_3_UI_ARCHITECTURE.md` Section 3.2), implement the PRD View as a standalone route with integrated discovery session support. The approach prioritizes:
1. **Component-first development**: Build reusable UI components matching the architecture's component hierarchy
2. **API integration**: Connect to existing v2 endpoints without backend changes
3. **Real-time streaming**: Implement SSE for discovery chat responses
4. **Progressive enhancement**: Start with core functionality (upload/edit PRD), then add discovery, then task generation

This aligns with the "golden path" philosophy—building only what's necessary for the core workflow.

## Implementation Steps

### 1. Create Route Structure

**Create PRD route pages:**
- Create `file:legacy/web-ui/src/app/prd/page.tsx` for main PRD editor view
- Create `file:legacy/web-ui/src/app/prd/discovery/page.tsx` for discovery session sub-view (optional, can be handled in main view with state)

**Update Navigation:**
- Modify `file:legacy/web-ui/src/components/Navigation.tsx` to add PRD navigation link (document icon)
- Add route to sidebar navigation per architecture Section 2

### 2. Define TypeScript Types

**Create PRD-specific types:**
- Create `file:legacy/web-ui/src/types/prd.ts` with interfaces:
  - `PrdRecord` (id, workspace_id, title, content, metadata, created_at, version, parent_id, change_summary, chain_id)
  - `DiscoverySession` (session_id, state, question, answered_count, is_complete)
  - `DiscoveryMessage` (role: 'user' | 'assistant', content, timestamp)
  - `TaskGenerationResult` (task_count, tasks)

**Update API client:**
- Extend `file:legacy/web-ui/src/lib/api.ts` with `prdV2Api` object containing:
  - `getLatest()` → GET `/api/v2/prd/latest`
  - `create(content, title?)` → POST `/api/v2/prd`
  - `update(prdId, content)` → POST `/api/v2/prd/{id}/versions`
  - `startDiscovery()` → POST `/api/v2/discovery/start`
  - `submitAnswer(sessionId, answer)` → POST `/api/v2/discovery/{session_id}/answer`
  - `generatePrd(sessionId)` → POST `/api/v2/discovery/{session_id}/generate-prd`
  - `generateTasks(prdId?)` → POST `/api/v2/discovery/generate-tasks`

### 3. Build Core Components

**Component hierarchy per architecture Section 3.2:**

#### PRDView (Main Container)
- Create `file:legacy/web-ui/src/components/prd/PRDView.tsx`
- State management: PRD content, discovery session, task summary
- Layout: Responsive grid (single column default, two-column when discovery active)
- Integrate all child components

#### PRDHeader
- Create `file:legacy/web-ui/src/components/prd/PRDHeader.tsx`
- Components:
  - **PRDTitle**: Inline editable title (contentEditable or input field)
  - **PRDActions**: Button group with Upload, Start Discovery, Generate Tasks
  - **PRDMetadata**: Display version, file path, timestamps
- Use Shadcn Button, Input components

#### PRDContent
- Create `file:legacy/web-ui/src/components/prd/PRDContent.tsx`
- Two-column layout using CSS Grid or Flexbox
- Left pane: MarkdownEditor (full-width when discovery inactive)
- Right pane: DiscoveryPanel (collapsible, slides in from right)

#### MarkdownEditor
- Create `file:legacy/web-ui/src/components/prd/MarkdownEditor.tsx`
- Use `react-markdown` (already in dependencies) for live preview
- Split view: Textarea for editing + rendered preview
- Debounced auto-save to prevent excessive API calls
- Syntax highlighting for code blocks via Shiki (mentioned in architecture)

#### DiscoveryPanel
- Create `file:legacy/web-ui/src/components/prd/DiscoveryPanel.tsx`
- Collapsible panel with slide-in animation (Tailwind transitions)
- Contains DiscoveryTranscript and DiscoveryInput
- Close button to collapse panel

#### DiscoveryTranscript
- Create `file:legacy/web-ui/src/components/prd/DiscoveryTranscript.tsx`
- Chat-style message list (similar to `file:legacy/web-ui/src/components/ChatInterface.tsx`)
- Message bubbles: User (right-aligned, primary color) vs AI (left-aligned, muted)
- AI avatar/branding icon (use Hugeicons)
- Auto-scroll to bottom on new messages
- Thinking indicator: Animated dots while AI generates response

#### DiscoveryInput
- Create `file:legacy/web-ui/src/components/prd/DiscoveryInput.tsx`
- Textarea with send button
- Character count indicator (max 10,000 per API)
- Keyboard shortcut: Ctrl+Enter to submit
- Disabled state while waiting for AI response

#### AssociatedTasksSummary
- Create `file:legacy/web-ui/src/components/prd/AssociatedTasksSummary.tsx`
- Compact badge display showing task counts by status
- Use Shadcn Badge component
- Format: "READY: 5 | IN_PROGRESS: 2 | DONE: 8"
- Click to navigate to `/tasks` view (future enhancement)

### 4. Implement Upload/Paste PRD Flow

**UploadPRDModal:**
- Create `file:legacy/web-ui/src/components/prd/UploadPRDModal.tsx`
- Shadcn Dialog component
- Two tabs: File Upload | Paste Markdown
- File upload: Accept `.md` files, read content via FileReader API
- Paste: Textarea for direct markdown input
- Validation: Check content length, markdown format
- On submit: Call `prdV2Api.create()`, update PRDView state

### 5. Implement Discovery Session Flow

**State management in PRDView:**
- Track discovery session state: `idle | discovering | completed`
- Store session_id, messages array, current question
- Use SWR for polling discovery status (optional, prefer SSE)

**Start Discovery:**
- Button click → Call `prdV2Api.startDiscovery()`
- Response contains session_id and first question
- Slide in DiscoveryPanel from right (CSS transform transition)
- Display first question in DiscoveryTranscript

**Answer Submission:**
- User types answer → Click send or Ctrl+Enter
- Show thinking indicator (animated dots)
- Call `prdV2Api.submitAnswer(sessionId, answer)`
- Response contains:
  - `accepted`: boolean (if false, show feedback)
  - `next_question`: Next question or null if complete
  - `is_complete`: boolean
- Append user message and AI response to transcript
- If complete, show "Generate PRD" button

**SSE Streaming (Optional Enhancement):**
- For streaming AI responses, implement SSE client
- Connect to `/api/v2/discovery/{session_id}/stream` (if endpoint exists)
- Display partial responses as they arrive (typewriter effect)

### 6. Implement PRD Generation from Discovery

**Generate PRD Button:**
- Enabled when discovery session is complete
- Click → Call `prdV2Api.generatePrd(sessionId)`
- Show loading spinner with progress message
- Response contains prd_id, title, preview
- Fetch full PRD via `prdV2Api.getLatest()`
- Populate MarkdownEditor with generated content
- Collapse DiscoveryPanel, show success toast

**Skip Discovery Option:**
- "Skip Discovery" button in DiscoveryPanel header
- Closes panel, allows manual PRD writing
- User can start discovery later if needed

### 7. Implement Task Generation

**Generate Tasks Button:**
- Located in PRDHeader actions
- Enabled when PRD exists (content not empty)
- Click → Call `prdV2Api.generateTasks()`
- Show loading modal with progress indicator
- Response contains task_count and task list
- Update AssociatedTasksSummary with counts
- Show success toast: "Generated X tasks"
- Optionally navigate to `/tasks` view

### 8. Add Real-time Updates

**SSE Integration for Discovery:**
- Create `file:legacy/web-ui/src/hooks/useDiscoveryStream.ts` custom hook
- Connect to SSE endpoint when discovery session active
- Listen for events:
  - `discovery_question_ready`: New question available
  - `discovery_completed`: Session finished
  - `prd_generation_started`: PRD generation began
  - `prd_generation_completed`: PRD ready
- Update component state based on events

**WebSocket Integration (Alternative):**
- Reuse existing WebSocket client from `file:legacy/web-ui/src/lib/websocket.ts`
- Subscribe to discovery events for project
- Handle same event types as SSE

### 9. Styling and Responsiveness

**Tailwind CSS Classes:**
- Use existing Shadcn/UI theme variables (bg-card, text-foreground, border-border)
- Two-column layout: `grid grid-cols-1 lg:grid-cols-2 gap-4`
- Discovery panel slide-in: `transform transition-transform duration-300 translate-x-0 lg:translate-x-full`
- Markdown preview: `prose prose-sm max-w-none` (Tailwind Typography)

**Mobile Responsiveness:**
- Stack columns vertically on mobile
- Discovery panel becomes full-screen overlay on small screens
- Collapsible sections for better mobile UX

### 10. Error Handling and Loading States

**Error Boundaries:**
- Wrap PRDView in ErrorBoundary component
- Display user-friendly error messages for API failures
- Retry buttons for transient errors

**Loading States:**
- Skeleton loaders for PRD content while fetching
- Spinner for discovery answer submission
- Progress bar for PRD/task generation
- Disabled states for buttons during operations

**Validation:**
- Client-side validation for answer length (1-10,000 chars)
- Markdown syntax validation (optional, warn on invalid syntax)
- Prevent duplicate submissions (debounce, disable button)

### 11. Testing Considerations

**Component Tests:**
- Test PRDView rendering with different states (idle, discovering, completed)
- Test MarkdownEditor editing and preview
- Test DiscoveryPanel message display and submission
- Mock API calls using MSW (already in dependencies)

**Integration Tests:**
- Test full discovery flow: start → answer questions → generate PRD
- Test upload PRD flow
- Test task generation from PRD

**E2E Tests (Future):**
- Full user journey from discovery to task generation

### 12. Documentation

**Update Architecture Docs:**
- Document component structure in `file:docs/PHASE_3_UI_ARCHITECTURE.md`
- Add screenshots/wireframes to docs

**Code Comments:**
- JSDoc comments for all components and functions
- Inline comments for complex logic (SSE handling, state management)

**README Updates:**
- Add PRD View to feature list
- Document discovery workflow for users

---

## Component Dependency Graph

```mermaid
graph TD
    A[PRDView] --> B[PRDHeader]
    A --> C[PRDContent]
    A --> D[AssociatedTasksSummary]
    
    B --> E[PRDTitle]
    B --> F[PRDActions]
    B --> G[PRDMetadata]
    
    F --> H[UploadPRDButton]
    F --> I[StartDiscoveryButton]
    F --> J[GenerateTasksButton]
    
    C --> K[MarkdownEditor]
    C --> L[DiscoveryPanel]
    
    L --> M[DiscoveryTranscript]
    L --> N[DiscoveryInput]
    
    H --> O[UploadPRDModal]
    
    style A fill:#e1f5ff
    style C fill:#fff4e1
    style L fill:#ffe1f5
```

## Discovery Session Flow

```mermaid
sequenceDiagram
    participant User
    participant PRDView
    participant API
    participant AI
    
    User->>PRDView: Click "Start Discovery"
    PRDView->>API: POST /api/v2/discovery/start
    API->>AI: Initialize session
    AI-->>API: First question
    API-->>PRDView: {session_id, question}
    PRDView->>PRDView: Show DiscoveryPanel
    
    loop Answer Questions
        User->>PRDView: Type answer + submit
        PRDView->>API: POST /api/v2/discovery/{id}/answer
        API->>AI: Validate & process answer
        AI-->>API: Next question or completion
        API-->>PRDView: {accepted, next_question, is_complete}
        PRDView->>PRDView: Update transcript
    end
    
    User->>PRDView: Click "Generate PRD"
    PRDView->>API: POST /api/v2/discovery/{id}/generate-prd
    API->>AI: Synthesize PRD from answers
    AI-->>API: Generated PRD content
    API-->>PRDView: {prd_id, title, content}
    PRDView->>PRDView: Populate MarkdownEditor
    PRDView->>PRDView: Collapse DiscoveryPanel
```

## File Structure

```
legacy/web-ui/src/
├── app/
│   └── prd/
│       ├── page.tsx                    # Main PRD route
│       └── discovery/
│           └── page.tsx                # Discovery sub-route (optional)
├── components/
│   ├── Navigation.tsx                  # Update with PRD link
│   └── prd/
│       ├── PRDView.tsx                 # Main container
│       ├── PRDHeader.tsx               # Header with actions
│       ├── PRDContent.tsx              # Two-column layout
│       ├── MarkdownEditor.tsx          # Editor + preview
│       ├── DiscoveryPanel.tsx          # Collapsible chat panel
│       ├── DiscoveryTranscript.tsx     # Message list
│       ├── DiscoveryInput.tsx          # Answer input
│       ├── AssociatedTasksSummary.tsx  # Task count badges
│       └── UploadPRDModal.tsx          # Upload/paste modal
├── hooks/
│   └── useDiscoveryStream.ts           # SSE hook for discovery
├── lib/
│   └── api.ts                          # Add prdV2Api methods
└── types/
    └── prd.ts                          # PRD-specific types
```

---

Execution Information

Branch: main
Commit: b252361

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

Warning

Something went wrong while processing your request.

Reference ID: 8b875f04-0866-42c0-9bb2-ba9718a7c840

Please try again or contact support if the issue persists, referencing this ID.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#194 - Fix PRD generation progress tracking UI [merged]
#196 - fix(discovery): Synchronize PRD buttons and fix state persistence on tab revisit [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#214 - feat(planning): Add TaskReview component for task approval workflow [merged]
#317 - feat(cli): add interactive PRD generation via Socratic discovery [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[frankbria]

Revise the implementation plan to not use /legacy/web-ui. All files should be under the /web-ui directory.

[frankbria]

Revised Implementation Plan (corrected file paths)

All files go under web-ui/, NOT legacy/web-ui/. The legacy/web-ui/ directory contains v1 reference code only.

Full plan document: docs/ISSUE_330_PRD_VIEW_PLAN.md

---

Key Corrections from Previous Plan

1. Directory: All paths changed from legacy/web-ui/src/... → web-ui/src/...
2. Existing patterns: API client follows the workspaceApi/tasksApi namespace pattern already in web-ui/src/lib/api.ts
3. Types: Extend the existing web-ui/src/types/index.ts barrel, add new web-ui/src/types/prd.ts
4. Icons: Use @hugeicons/react (not lucide-react) per Nova template
5. API endpoints: Verified against actual backend routers (prd_v2.py, discovery_v2.py)

---

File Structure

web-ui/src/
├── app/
│   └── prd/
│       ├── page.tsx                    # Main PRD route
│       └── discovery/
│           └── page.tsx                # Discovery sub-route (optional)
├── components/
│   └── prd/
│       ├── PRDView.tsx                 # Main container
│       ├── PRDHeader.tsx               # Header with actions
│       ├── PRDContent.tsx              # Two-column layout
│       ├── MarkdownEditor.tsx          # Editor + preview
│       ├── DiscoveryPanel.tsx          # Collapsible chat panel
│       ├── DiscoveryTranscript.tsx     # Message list
│       ├── DiscoveryInput.tsx          # Answer input
│       ├── AssociatedTasksSummary.tsx  # Task count badges
│       ├── UploadPRDModal.tsx          # Upload/paste modal
│       └── index.ts                    # Barrel export
├── hooks/
│   └── useDiscoveryStream.ts           # SSE hook for discovery
├── lib/
│   └── api.ts                          # Add prdApi + discoveryApi
└── types/
    ├── index.ts                        # Re-export prd types
    └── prd.ts                          # PRD-specific types

API Endpoints (verified)

PRD (/api/v2/prd):

Method	Path	Purpose
GET	/api/v2/prd	List PRDs
GET	/api/v2/prd/latest	Get latest
POST	/api/v2/prd	Create PRD
GET	/api/v2/prd/{id}/versions	Version history
POST	/api/v2/prd/{id}/versions	New version

Discovery (/api/v2/discovery):

Method	Path	Purpose
POST	/api/v2/discovery/start	Start session
GET	/api/v2/discovery/status	Session status
POST	/api/v2/discovery/{session_id}/answer	Submit answer
POST	/api/v2/discovery/{session_id}/generate-prd	Generate PRD
POST	/api/v2/discovery/generate-tasks	Generate tasks

Acceptance Criteria Mapping

Criterion	Component	Step
Upload PRD via file picker or paste	UploadPRDModal	5
Markdown editor with live preview	MarkdownEditor	4
Discovery session launches chat panel	DiscoveryPanel	6
Chat-style with AI avatar/branding	DiscoveryTranscript	6
Thinking indicator	DiscoveryTranscript	6
Discovery panel slides in from right	DiscoveryPanel	6
"Skip discovery" option	DiscoveryPanel close button	6
Generate tasks button	PRDHeader → PRDActions	7
Task counts by status	AssociatedTasksSummary	7
Responsive two-column layout	PRDContent	4

Implementation Order

1. Types + API client (foundation)
2. PRD route + PRDView shell
3. PRDHeader + UploadPRDModal
4. MarkdownEditor
5. DiscoveryPanel + Transcript + Input
6. AssociatedTasksSummary + task generation
7. SSE hook (enhancement)
8. Navigation sidebar link
9. Testing