[P3] Refactor: Split DiscoveryProgress.tsx (1,165 lines) into focused components

[frankbria]

Problem

DiscoveryProgress.tsx at 1,165 lines is a single-file component handling the entire discovery workflow with 40+ state variables.

Current State

• File: web-ui/src/components/DiscoveryProgress.tsx (~1,165 lines)
• Manages: Idle state, question display, answer input, PRD generation, task generation, restart confirmation
• Contains: Complex phase state machine, progress tracking, error handling

Impact

• Extremely hard to maintain
• State management is tangled
• Testing requires extensive mocking
• Any change risks regression in unrelated parts

Required Decomposition

New Structure

web-ui/src/components/discovery/
├── DiscoveryProgress.tsx      # Container/state machine (~300 lines)
├── DiscoveryIdle.tsx          # "Start Discovery" prompt
├── DiscoveryQuestion.tsx      # Current question display
├── DiscoveryAnswer.tsx        # Answer input form
├── DiscoveryPRDGeneration.tsx # PRD generation progress
├── DiscoveryTaskGeneration.tsx # Task generation progress
├── DiscoveryComplete.tsx      # Completion state
└── hooks/
    └── useDiscoveryState.ts   # State management hook

State Flow

DiscoveryProgress (container)
    │
    ├── phase === 'idle' → DiscoveryIdle
    ├── phase === 'questioning' → DiscoveryQuestion + DiscoveryAnswer
    ├── phase === 'generating_prd' → DiscoveryPRDGeneration
    ├── phase === 'generating_tasks' → DiscoveryTaskGeneration
    └── phase === 'complete' → DiscoveryComplete

Acceptance Criteria

• DiscoveryProgress.tsx reduced to <350 lines
• Each sub-component handles one phase
• Custom hook extracts state logic
• All existing tests pass
• No visual regression

Committee Report Reference

Frontend Architect flagged as "1,165 lines is a single-file component". UX/UI Designer: "Single section tries to serve 4 different phases."

[traycerai]

Plan

Observations

The file:web-ui/src/components/DiscoveryProgress.tsx component is a monolithic 1,165-line file managing the entire discovery workflow with 40+ state variables. It handles five distinct phases (idle, discovering, PRD generation, task generation, complete) with complex WebSocket event handling, progress tracking, error recovery, and UI state management. The codebase already follows patterns for component decomposition (subdirectories like quality-gates/, metrics/) and state management (custom hooks with useCallback/useMemo, Context+Reducer pattern as seen in file:web-ui/src/hooks/useAgentState.ts). The component has extensive test coverage with 8 dedicated test files totaling 3,700+ lines.

Approach

Split the monolithic component into a container-presentation architecture using a dedicated discovery/ subdirectory. Extract state management into a custom useDiscoveryState hook following the established pattern from useAgentState. Create focused phase-specific components that receive props from the container. This maintains all existing functionality, WebSocket handling, and test coverage while dramatically improving maintainability. The refactoring aligns with the codebase's existing patterns and keeps the component tree shallow for optimal performance.

Implementation Steps

1. Create Discovery Directory Structure

Create file:web-ui/src/components/discovery/ directory with the following structure:

web-ui/src/components/discovery/
├── DiscoveryProgress.tsx          # Container component
├── DiscoveryIdle.tsx              # Idle state component
├── DiscoveryQuestion.tsx          # Question display component
├── DiscoveryAnswer.tsx            # Answer input form
├── DiscoveryPRDGeneration.tsx     # PRD generation progress
├── DiscoveryTaskGeneration.tsx    # Task generation progress
├── DiscoveryComplete.tsx          # Completion state
├── DiscoveryMinimized.tsx         # Minimized view
├── hooks/
│   └── useDiscoveryState.ts       # State management hook
└── types.ts                       # Shared types for discovery components

2. Extract State Management Hook

Create file:web-ui/src/components/discovery/hooks/useDiscoveryState.ts

Extract all state variables and handlers from the current component into a custom hook following the pattern established in file:web-ui/src/hooks/useAgentState.ts:

• State groups to extract:

  • Data/Loading/Error state (3 variables)
  • Answer submission state (5 variables)
  • Start discovery state (2 variables)
  • PRD generation state (6 variables)
  • UI state (1 variable)
  • Stuck detection state (4 variables)
  • PRD retry state (1 variable)
  • Task generation state (8 variables)
  • Refs (1 variable)

• Handlers to extract:

  • submitAnswer - Answer submission with validation
  • handleKeyPress - Keyboard shortcut handler
  • fetchProgress - Progress fetching with PRD/task initialization
  • handleStartDiscovery - Start discovery workflow
  • handleRestartDiscovery - Restart stuck discovery
  • handleRetryPrdGeneration - Retry failed PRD generation
  • handleGenerateTaskBreakdown - Generate tasks from PRD

• WebSocket effects to extract:

  • Discovery event handlers (discovery_starting, discovery_reset, question_ready)
  • PRD generation event handlers (prd_generation_started, prd_generation_progress, prd_generation_completed, prd_generation_failed)
  • Task generation event handlers (planning_started, issues_generated, tasks_decomposed, tasks_ready)
  • Stuck state detection timer
  • Auto-refresh during discovery
  • Auto-minimize after PRD completion

• Return interface:

  interface UseDiscoveryStateReturn {
    // Data state
    data: DiscoveryProgressResponse | null;
    loading: boolean;
    error: string | null;
    
    // Phase helpers
    isIdle: boolean;
    isDiscovering: boolean;
    isCompleted: boolean;
    
    // Answer state
    answer: string;
    setAnswer: (value: string) => void;
    isSubmitting: boolean;
    submissionError: string | null;
    showSuccessMessage: boolean;
    isLoadingNextQuestion: boolean;
    
    // Start discovery
    isStarting: boolean;
    startError: string | null;
    handleStartDiscovery: () => Promise<void>;
    
    // PRD generation
    isGeneratingPRD: boolean;
    prdCompleted: boolean;
    prdError: string | null;
    prdStage: string;
    prdMessage: string;
    prdProgressPct: number;
    isRetryingPrd: boolean;
    handleRetryPrdGeneration: () => Promise<void>;
    
    // Task generation
    tasksGenerated: boolean;
    isGeneratingTasks: boolean;
    taskGenerationError: string | null;
    taskGenerationProgress: string;
    issuesCount: number;
    tasksCount: number;
    taskStateInitialized: boolean;
    tasksAlreadyExistMessage: boolean;
    handleGenerateTaskBreakdown: () => Promise<void>;
    
    // Stuck state
    isStuck: boolean;
    isRestarting: boolean;
    restartError: string | null;
    handleRestartDiscovery: () => Promise<void>;
    
    // UI state
    isSectionMinimized: boolean;
    setIsSectionMinimized: (value: boolean) => void;
    
    // Handlers
    submitAnswer: () => Promise<void>;
    handleKeyPress: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
  }

Use useCallback for all handlers and useMemo for derived state following the pattern in file:web-ui/src/hooks/useAgentState.ts.

3. Create Shared Types File

Create file:web-ui/src/components/discovery/types.ts

Define shared prop interfaces for all discovery components:

export interface DiscoveryBaseProps {
  projectId: number;
}

export interface DiscoveryIdleProps extends DiscoveryBaseProps {
  isStarting: boolean;
  startError: string | null;
  onStartDiscovery: () => Promise<void>;
}

export interface DiscoveryQuestionProps {
  question: string;
  category: string;
  questionIndex: number;
  totalQuestions: number;
  progressPercentage: number;
  answeredCount: number;
}

export interface DiscoveryAnswerProps {
  answer: string;
  onAnswerChange: (value: string) => void;
  onSubmit: () => Promise<void>;
  onKeyPress: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
  isSubmitting: boolean;
  isLoadingNextQuestion: boolean;
  submissionError: string | null;
  showSuccessMessage: boolean;
}

export interface DiscoveryPRDGenerationProps {
  isGenerating: boolean;
  completed: boolean;
  error: string | null;
  stage: string;
  message: string;
  progressPct: number;
  isRetrying: boolean;
  onRetry: () => Promise<void>;
  onViewPRD?: () => void;
  onRestart: () => Promise<void>;
  isRestarting: boolean;
  restartError: string | null;
}

export interface DiscoveryTaskGenerationProps {
  phase: string;
  prdCompleted: boolean;
  tasksGenerated: boolean;
  isGenerating: boolean;
  error: string | null;
  progress: string;
  issuesCount: number;
  tasksCount: number;
  taskStateInitialized: boolean;
  tasksAlreadyExistMessage: boolean;
  onGenerate: () => Promise<void>;
  onNavigateToTasks?: () => void;
}

export interface DiscoveryMinimizedProps {
  onExpand: () => void;
  onViewPRD?: () => void;
  onRestart: () => Promise<void>;
  isRestarting: boolean;
}

export interface DiscoveryStuckProps {
  onRestart: () => Promise<void>;
  isRestarting: boolean;
  restartError: string | null;
}

4. Create Phase-Specific Components

Create file:web-ui/src/components/discovery/DiscoveryIdle.tsx

Extract idle state UI (lines 1012-1040 from original):

• "Discovery not started" message
• "Start Discovery" button with loading state
• Error display for start failures
• Import and use types from file:web-ui/src/components/discovery/types.ts

Create file:web-ui/src/components/discovery/DiscoveryQuestion.tsx

Extract question display UI (lines 586-620 from original):

• Progress bar using file:web-ui/src/components/ProgressBar.tsx
• Answered count display
• Current question card with category badge
• Loading state for next question
• Import types from file:web-ui/src/components/discovery/types.ts

Create file:web-ui/src/components/discovery/DiscoveryAnswer.tsx

Extract answer input form (lines 677-742 from original):

• Textarea with character counter
• Submit button with loading state
• Success message display
• Error message display
• Keyboard shortcut hint
• Character count color coding (>4500 = red)
• Import types from file:web-ui/src/components/discovery/types.ts

Create file:web-ui/src/components/discovery/DiscoveryStuck.tsx

Extract stuck state UI (lines 623-675 from original):

• Stuck detection warning with Alert02Icon from @hugeicons/react
• Restart button
• Error display for restart failures
• Waiting spinner for normal loading
• Import types from file:web-ui/src/components/discovery/types.ts

Create file:web-ui/src/components/discovery/DiscoveryPRDGeneration.tsx

Extract PRD generation UI (lines 815-918 from original):

• Discovery complete banner with CheckmarkCircle01Icon from @hugeicons/react
• PRD generation progress with stage/message/percentage
• PRD completed state with "View PRD" button
• PRD error state with retry button
• Minimize button when completed
• Restart discovery button
• Import types from file:web-ui/src/components/discovery/types.ts

Create file:web-ui/src/components/discovery/DiscoveryTaskGeneration.tsx

Extract task generation UI (lines 920-1006 from original):

• "Generate Task Breakdown" button (shown when PRD complete, planning phase, no tasks)
• Task generation progress with spinner
• Task generation error with retry
• Tasks ready state with issue/task counts
• "Review Tasks" navigation button
• Handle tasksAlreadyExistMessage notification
• Import types from file:web-ui/src/components/discovery/types.ts

Create file:web-ui/src/components/discovery/DiscoveryMinimized.tsx

Extract minimized view UI (lines 750-792 from original):

• Compact banner with checkmark icon
• "Discovery Complete / PRD Generated" text
• "View PRD" button
• "Restart" button
• "Expand" button
• Import types from file:web-ui/src/components/discovery/types.ts

Create file:web-ui/src/components/discovery/DiscoveryComplete.tsx

Compose the completed state from sub-components:

• Render DiscoveryMinimized when isSectionMinimized is true
• Otherwise render DiscoveryPRDGeneration and DiscoveryTaskGeneration
• Handle minimize/expand toggle
• Import all necessary sub-components

5. Refactor Container Component

Refactor file:web-ui/src/components/discovery/DiscoveryProgress.tsx

Transform into a lean container component (~250-300 lines):

'use client';

import { memo } from 'react';
import PhaseIndicator from '../PhaseIndicator';
import DiscoveryIdle from './DiscoveryIdle';
import DiscoveryQuestion from './DiscoveryQuestion';
import DiscoveryAnswer from './DiscoveryAnswer';
import DiscoveryStuck from './DiscoveryStuck';
import DiscoveryComplete from './DiscoveryComplete';
import { useDiscoveryState } from './hooks/useDiscoveryState';

interface DiscoveryProgressProps {
  projectId: number;
  onViewPRD?: () => void;
  onNavigateToTasks?: () => void;
}

const DiscoveryProgress = memo(function DiscoveryProgress({ 
  projectId, 
  onViewPRD, 
  onNavigateToTasks 
}: DiscoveryProgressProps) {
  const state = useDiscoveryState(projectId);
  
  // Loading state
  if (state.loading) {
    return (
      <div className="w-full bg-card rounded-lg shadow p-6" role="region" aria-label="Discovery Progress">
        <div className="text-center text-muted-foreground">Loading...</div>
      </div>
    );
  }
  
  // Error state
  if (state.error) {
    return (
      <div className="w-full bg-card rounded-lg shadow p-6" role="region" aria-label="Discovery Progress">
        <div className="text-center text-destructive">{state.error}</div>
      </div>
    );
  }
  
  if (!state.data) {
    return null;
  }
  
  return (
    <div className="w-full bg-card rounded-lg shadow p-6 mb-6" role="region" aria-label="Discovery Progress" data-testid="discovery-progress">
      <div className="flex items-center justify-between mb-4">
        <h2 className="text-lg font-semibold">Discovery Progress</h2>
        <PhaseIndicator phase={state.data.phase} />
      </div>
      
      <div className="space-y-4">
        {/* Success message - shown in any state */}
        {state.showSuccessMessage && (
          <div className="mt-4 p-3 rounded-lg border bg-success/10 border-success text-success" data-testid="success-message">
            Answer submitted! Loading next question...
          </div>
        )}
        
        {/* Idle State */}
        {state.isIdle && (
          <DiscoveryIdle
            projectId={projectId}
            isStarting={state.isStarting}
            startError={state.startError}
            onStartDiscovery={state.handleStartDiscovery}
          />
        )}
        
        {/* Discovering State */}
        {state.isDiscovering && state.data.discovery && (
          <>
            <DiscoveryQuestion
              question={state.data.discovery.current_question?.question || ''}
              category={state.data.discovery.current_question?.category || ''}
              questionIndex={state.data.discovery.answered_count + 1}
              totalQuestions={state.data.discovery.total_required}
              progressPercentage={state.data.discovery.progress_percentage}
              answeredCount={state.data.discovery.answered_count}
            />
            
            {/* Show stuck state or answer input */}
            {!state.data.discovery.current_question && !state.isLoadingNextQuestion && (
              <DiscoveryStuck
                onRestart={state.handleRestartDiscovery}
                isRestarting={state.isRestarting}
                restartError={state.restartError}
              />
            )}
            
            {state.data.discovery.current_question && !state.isLoadingNextQuestion && (
              <DiscoveryAnswer
                answer={state.answer}
                onAnswerChange={state.setAnswer}
                onSubmit={state.submitAnswer}
                onKeyPress={state.handleKeyPress}
                isSubmitting={state.isSubmitting}
                isLoadingNextQuestion={state.isLoadingNextQuestion}
                submissionError={state.submissionError}
                showSuccessMessage={state.showSuccessMessage}
              />
            )}
          </>
        )}
        
        {/* Completed State */}
        {state.isCompleted && (
          <DiscoveryComplete
            projectId={projectId}
            phase={state.data.phase}
            isSectionMinimized={state.isSectionMinimized}
            onMinimize={() => state.setIsSectionMinimized(true)}
            onExpand={() => state.setIsSectionMinimized(false)}
            isGeneratingPRD={state.isGeneratingPRD}
            prdCompleted={state.prdCompleted}
            prdError={state.prdError}
            prdStage={state.prdStage}
            prdMessage={state.prdMessage}
            prdProgressPct={state.prdProgressPct}
            isRetryingPrd={state.isRetryingPrd}
            onRetryPrd={state.handleRetryPrdGeneration}
            onViewPRD={onViewPRD}
            onRestart={state.handleRestartDiscovery}
            isRestarting={state.isRestarting}
            restartError={state.restartError}
            tasksGenerated={state.tasksGenerated}
            isGeneratingTasks={state.isGeneratingTasks}
            taskGenerationError={state.taskGenerationError}
            taskGenerationProgress={state.taskGenerationProgress}
            issuesCount={state.issuesCount}
            tasksCount={state.tasksCount}
            taskStateInitialized={state.taskStateInitialized}
            tasksAlreadyExistMessage={state.tasksAlreadyExistMessage}
            onGenerateTasks={state.handleGenerateTaskBreakdown}
            onNavigateToTasks={onNavigateToTasks}
          />
        )}
      </div>
    </div>
  );
});

DiscoveryProgress.displayName = 'DiscoveryProgress';
export default DiscoveryProgress;

6. Update Import Path

Update file:web-ui/src/components/DiscoveryProgress.tsx (original location)

Replace the entire file with a re-export to maintain backward compatibility:

/**
 * DiscoveryProgress Component
 * 
 * Re-export from discovery/ subdirectory for backward compatibility.
 * The component has been refactored into focused sub-components.
 * 
 * @see web-ui/src/components/discovery/DiscoveryProgress.tsx
 */
export { default } from './discovery/DiscoveryProgress';

7. Update Test Files

Update all test files in file:web-ui/__tests__/components/:

• DiscoveryProgress.test.tsx
• DiscoveryProgress.advanced.test.tsx
• DiscoveryProgress.answer.test.tsx
• DiscoveryProgress.core.test.tsx
• DiscoveryProgress.error.test.tsx
• DiscoveryProgress.prd.test.tsx
• DiscoveryProgress.progress.test.tsx
• DiscoveryProgress.websocket.test.tsx

Changes needed:

1. Update import path from @/components/DiscoveryProgress to @/components/discovery/DiscoveryProgress
2. Add new test file file:web-ui/__tests__/components/discovery/useDiscoveryState.test.tsx for the custom hook
3. Optionally add unit tests for individual phase components (DiscoveryIdle, DiscoveryQuestion, etc.)
4. Verify all existing tests pass without modification (they should, as the container maintains the same data-testid attributes)

Update file:web-ui/__tests__/components/DiscoveryProgress.testutils.tsx:

• Update import path for DiscoveryProgress component
• No other changes needed as mocks remain the same

8. Verification Checklist

After implementation, verify:

1. Line count targets:

   • DiscoveryProgress.tsx (container): <300 lines ✓
   • useDiscoveryState.ts: ~400-500 lines
   • Each phase component: <150 lines
   • Total: ~1,200-1,300 lines (slight increase due to type definitions and imports, but much better organized)

2. Functionality preservation:

   • All 8 test suites pass without modification
   • WebSocket events handled correctly
   • State transitions work as before
   • No visual regressions (test with data-testid attributes)

3. Code quality:

   • All TypeScript types properly defined
   • No any types used
   • Proper use of memo, useCallback, useMemo
   • Consistent naming conventions
   • All imports use @/ alias

4. Performance:

   • No unnecessary re-renders (use React DevTools Profiler)
   • WebSocket cleanup on unmount
   • Timer cleanup in useEffect hooks

Component Interaction Flow

sequenceDiagram
    participant User
    participant Container as DiscoveryProgress<br/>(Container)
    participant Hook as useDiscoveryState<br/>(Hook)
    participant Idle as DiscoveryIdle
    participant Question as DiscoveryQuestion
    participant Answer as DiscoveryAnswer
    participant PRD as DiscoveryPRDGeneration
    participant Tasks as DiscoveryTaskGeneration
    participant WS as WebSocket

    User->>Container: Load component
    Container->>Hook: useDiscoveryState(projectId)
    Hook->>Hook: Fetch initial data
    Hook->>WS: Subscribe to events
    Hook-->>Container: Return state & handlers
    
    alt Idle State
        Container->>Idle: Render with handlers
        User->>Idle: Click "Start Discovery"
        Idle->>Hook: handleStartDiscovery()
        Hook->>WS: Start discovery
        WS-->>Hook: discovery_starting event
        Hook->>Hook: Update state
        Hook-->>Container: isDiscovering = true
    end
    
    alt Discovering State
        Container->>Question: Render progress
        Container->>Answer: Render input form
        User->>Answer: Type answer & submit
        Answer->>Hook: submitAnswer()
        Hook->>Hook: Validate & POST
        WS-->>Hook: question_ready event
        Hook->>Hook: Update question
        Hook-->>Container: New question data
        Container->>Question: Re-render with new question
    end
    
    alt Completed State
        WS-->>Hook: discovery_complete event
        Hook->>Hook: isCompleted = true
        Hook-->>Container: State update
        Container->>PRD: Render PRD generation
        WS-->>Hook: prd_generation_progress
        Hook-->>PRD: Update progress
        WS-->>Hook: prd_generation_completed
        Hook->>Hook: prdCompleted = true
        Hook-->>Container: State update
        Container->>Tasks: Render task generation
        User->>Tasks: Click "Generate Tasks"
        Tasks->>Hook: handleGenerateTaskBreakdown()
        WS-->>Hook: tasks_ready event
        Hook-->>Container: tasksGenerated = true
    end

Loading

File Size Comparison

Component	Before	After	Change
DiscoveryProgress.tsx	1,165 lines	~250 lines	-915 lines (-78%)
useDiscoveryState.ts	-	~450 lines	+450 lines (new)
DiscoveryIdle.tsx	-	~40 lines	+40 lines (new)
DiscoveryQuestion.tsx	-	~80 lines	+80 lines (new)
DiscoveryAnswer.tsx	-	~120 lines	+120 lines (new)
DiscoveryStuck.tsx	-	~60 lines	+60 lines (new)
DiscoveryPRDGeneration.tsx	-	~150 lines	+150 lines (new)
DiscoveryTaskGeneration.tsx	-	~140 lines	+140 lines (new)
DiscoveryMinimized.tsx	-	~50 lines	+50 lines (new)
DiscoveryComplete.tsx	-	~80 lines	+80 lines (new)
types.ts	-	~100 lines	+100 lines (new)
Total	1,165 lines	~1,520 lines	+355 lines (+30%)

The total line count increases due to:

• Type definitions and interfaces
• Import statements in each file
• Component boundaries and exports
• Improved code organization and readability

However, maintainability improves dramatically:

• Each file has a single, clear responsibility
• State logic is isolated and testable
• Components are reusable and composable
• Changes to one phase don't affect others

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `file:web-ui/src/components/DiscoveryProgress.tsx` component is a monolithic 1,165-line file managing the entire discovery workflow with 40+ state variables. It handles five distinct phases (idle, discovering, PRD generation, task generation, complete) with complex WebSocket event handling, progress tracking, error recovery, and UI state management. The codebase already follows patterns for component decomposition (subdirectories like `quality-gates/`, `metrics/`) and state management (custom hooks with `useCallback`/`useMemo`, Context+Reducer pattern as seen in `file:web-ui/src/hooks/useAgentState.ts`). The component has extensive test coverage with 8 dedicated test files totaling 3,700+ lines.

## Approach

Split the monolithic component into a container-presentation architecture using a dedicated `discovery/` subdirectory. Extract state management into a custom `useDiscoveryState` hook following the established pattern from `useAgentState`. Create focused phase-specific components that receive props from the container. This maintains all existing functionality, WebSocket handling, and test coverage while dramatically improving maintainability. The refactoring aligns with the codebase's existing patterns and keeps the component tree shallow for optimal performance.

## Implementation Steps

### 1. Create Discovery Directory Structure

Create `file:web-ui/src/components/discovery/` directory with the following structure:

```
web-ui/src/components/discovery/
├── DiscoveryProgress.tsx          # Container component
├── DiscoveryIdle.tsx              # Idle state component
├── DiscoveryQuestion.tsx          # Question display component
├── DiscoveryAnswer.tsx            # Answer input form
├── DiscoveryPRDGeneration.tsx     # PRD generation progress
├── DiscoveryTaskGeneration.tsx    # Task generation progress
├── DiscoveryComplete.tsx          # Completion state
├── DiscoveryMinimized.tsx         # Minimized view
├── hooks/
│   └── useDiscoveryState.ts       # State management hook
└── types.ts                       # Shared types for discovery components
```

### 2. Extract State Management Hook

**Create `file:web-ui/src/components/discovery/hooks/useDiscoveryState.ts`**

Extract all state variables and handlers from the current component into a custom hook following the pattern established in `file:web-ui/src/hooks/useAgentState.ts`:

- **State groups to extract:**
  - Data/Loading/Error state (3 variables)
  - Answer submission state (5 variables)
  - Start discovery state (2 variables)
  - PRD generation state (6 variables)
  - UI state (1 variable)
  - Stuck detection state (4 variables)
  - PRD retry state (1 variable)
  - Task generation state (8 variables)
  - Refs (1 variable)

- **Handlers to extract:**
  - `submitAnswer` - Answer submission with validation
  - `handleKeyPress` - Keyboard shortcut handler
  - `fetchProgress` - Progress fetching with PRD/task initialization
  - `handleStartDiscovery` - Start discovery workflow
  - `handleRestartDiscovery` - Restart stuck discovery
  - `handleRetryPrdGeneration` - Retry failed PRD generation
  - `handleGenerateTaskBreakdown` - Generate tasks from PRD

- **WebSocket effects to extract:**
  - Discovery event handlers (discovery_starting, discovery_reset, question_ready)
  - PRD generation event handlers (prd_generation_started, prd_generation_progress, prd_generation_completed, prd_generation_failed)
  - Task generation event handlers (planning_started, issues_generated, tasks_decomposed, tasks_ready)
  - Stuck state detection timer
  - Auto-refresh during discovery
  - Auto-minimize after PRD completion

- **Return interface:**
  ```typescript
  interface UseDiscoveryStateReturn {
    // Data state
    data: DiscoveryProgressResponse | null;
    loading: boolean;
    error: string | null;
    
    // Phase helpers
    isIdle: boolean;
    isDiscovering: boolean;
    isCompleted: boolean;
    
    // Answer state
    answer: string;
    setAnswer: (value: string) => void;
    isSubmitting: boolean;
    submissionError: string | null;
    showSuccessMessage: boolean;
    isLoadingNextQuestion: boolean;
    
    // Start discovery
    isStarting: boolean;
    startError: string | null;
    handleStartDiscovery: () => Promise<void>;
    
    // PRD generation
    isGeneratingPRD: boolean;
    prdCompleted: boolean;
    prdError: string | null;
    prdStage: string;
    prdMessage: string;
    prdProgressPct: number;
    isRetryingPrd: boolean;
    handleRetryPrdGeneration: () => Promise<void>;
    
    // Task generation
    tasksGenerated: boolean;
    isGeneratingTasks: boolean;
    taskGenerationError: string | null;
    taskGenerationProgress: string;
    issuesCount: number;
    tasksCount: number;
    taskStateInitialized: boolean;
    tasksAlreadyExistMessage: boolean;
    handleGenerateTaskBreakdown: () => Promise<void>;
    
    // Stuck state
    isStuck: boolean;
    isRestarting: boolean;
    restartError: string | null;
    handleRestartDiscovery: () => Promise<void>;
    
    // UI state
    isSectionMinimized: boolean;
    setIsSectionMinimized: (value: boolean) => void;
    
    // Handlers
    submitAnswer: () => Promise<void>;
    handleKeyPress: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
  }
  ```

Use `useCallback` for all handlers and `useMemo` for derived state following the pattern in `file:web-ui/src/hooks/useAgentState.ts`.

### 3. Create Shared Types File

**Create `file:web-ui/src/components/discovery/types.ts`**

Define shared prop interfaces for all discovery components:

```typescript
export interface DiscoveryBaseProps {
  projectId: number;
}

export interface DiscoveryIdleProps extends DiscoveryBaseProps {
  isStarting: boolean;
  startError: string | null;
  onStartDiscovery: () => Promise<void>;
}

export interface DiscoveryQuestionProps {
  question: string;
  category: string;
  questionIndex: number;
  totalQuestions: number;
  progressPercentage: number;
  answeredCount: number;
}

export interface DiscoveryAnswerProps {
  answer: string;
  onAnswerChange: (value: string) => void;
  onSubmit: () => Promise<void>;
  onKeyPress: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
  isSubmitting: boolean;
  isLoadingNextQuestion: boolean;
  submissionError: string | null;
  showSuccessMessage: boolean;
}

export interface DiscoveryPRDGenerationProps {
  isGenerating: boolean;
  completed: boolean;
  error: string | null;
  stage: string;
  message: string;
  progressPct: number;
  isRetrying: boolean;
  onRetry: () => Promise<void>;
  onViewPRD?: () => void;
  onRestart: () => Promise<void>;
  isRestarting: boolean;
  restartError: string | null;
}

export interface DiscoveryTaskGenerationProps {
  phase: string;
  prdCompleted: boolean;
  tasksGenerated: boolean;
  isGenerating: boolean;
  error: string | null;
  progress: string;
  issuesCount: number;
  tasksCount: number;
  taskStateInitialized: boolean;
  tasksAlreadyExistMessage: boolean;
  onGenerate: () => Promise<void>;
  onNavigateToTasks?: () => void;
}

export interface DiscoveryMinimizedProps {
  onExpand: () => void;
  onViewPRD?: () => void;
  onRestart: () => Promise<void>;
  isRestarting: boolean;
}

export interface DiscoveryStuckProps {
  onRestart: () => Promise<void>;
  isRestarting: boolean;
  restartError: string | null;
}
```

### 4. Create Phase-Specific Components

#### **Create `file:web-ui/src/components/discovery/DiscoveryIdle.tsx`**

Extract idle state UI (lines 1012-1040 from original):
- "Discovery not started" message
- "Start Discovery" button with loading state
- Error display for start failures
- Import and use types from `file:web-ui/src/components/discovery/types.ts`

#### **Create `file:web-ui/src/components/discovery/DiscoveryQuestion.tsx`**

Extract question display UI (lines 586-620 from original):
- Progress bar using `file:web-ui/src/components/ProgressBar.tsx`
- Answered count display
- Current question card with category badge
- Loading state for next question
- Import types from `file:web-ui/src/components/discovery/types.ts`

#### **Create `file:web-ui/src/components/discovery/DiscoveryAnswer.tsx`**

Extract answer input form (lines 677-742 from original):
- Textarea with character counter
- Submit button with loading state
- Success message display
- Error message display
- Keyboard shortcut hint
- Character count color coding (>4500 = red)
- Import types from `file:web-ui/src/components/discovery/types.ts`

#### **Create `file:web-ui/src/components/discovery/DiscoveryStuck.tsx`**

Extract stuck state UI (lines 623-675 from original):
- Stuck detection warning with `Alert02Icon` from `@hugeicons/react`
- Restart button
- Error display for restart failures
- Waiting spinner for normal loading
- Import types from `file:web-ui/src/components/discovery/types.ts`

#### **Create `file:web-ui/src/components/discovery/DiscoveryPRDGeneration.tsx`**

Extract PRD generation UI (lines 815-918 from original):
- Discovery complete banner with `CheckmarkCircle01Icon` from `@hugeicons/react`
- PRD generation progress with stage/message/percentage
- PRD completed state with "View PRD" button
- PRD error state with retry button
- Minimize button when completed
- Restart discovery button
- Import types from `file:web-ui/src/components/discovery/types.ts`

#### **Create `file:web-ui/src/components/discovery/DiscoveryTaskGeneration.tsx`**

Extract task generation UI (lines 920-1006 from original):
- "Generate Task Breakdown" button (shown when PRD complete, planning phase, no tasks)
- Task generation progress with spinner
- Task generation error with retry
- Tasks ready state with issue/task counts
- "Review Tasks" navigation button
- Handle `tasksAlreadyExistMessage` notification
- Import types from `file:web-ui/src/components/discovery/types.ts`

#### **Create `file:web-ui/src/components/discovery/DiscoveryMinimized.tsx`**

Extract minimized view UI (lines 750-792 from original):
- Compact banner with checkmark icon
- "Discovery Complete / PRD Generated" text
- "View PRD" button
- "Restart" button
- "Expand" button
- Import types from `file:web-ui/src/components/discovery/types.ts`

#### **Create `file:web-ui/src/components/discovery/DiscoveryComplete.tsx`**

Compose the completed state from sub-components:
- Render `DiscoveryMinimized` when `isSectionMinimized` is true
- Otherwise render `DiscoveryPRDGeneration` and `DiscoveryTaskGeneration`
- Handle minimize/expand toggle
- Import all necessary sub-components

### 5. Refactor Container Component

**Refactor `file:web-ui/src/components/discovery/DiscoveryProgress.tsx`**

Transform into a lean container component (~250-300 lines):

```typescript
'use client';

import { memo } from 'react';
import PhaseIndicator from '../PhaseIndicator';
import DiscoveryIdle from './DiscoveryIdle';
import DiscoveryQuestion from './DiscoveryQuestion';
import DiscoveryAnswer from './DiscoveryAnswer';
import DiscoveryStuck from './DiscoveryStuck';
import DiscoveryComplete from './DiscoveryComplete';
import { useDiscoveryState } from './hooks/useDiscoveryState';

interface DiscoveryProgressProps {
  projectId: number;
  onViewPRD?: () => void;
  onNavigateToTasks?: () => void;
}

const DiscoveryProgress = memo(function DiscoveryProgress({ 
  projectId, 
  onViewPRD, 
  onNavigateToTasks 
}: DiscoveryProgressProps) {
  const state = useDiscoveryState(projectId);
  
  // Loading state
  if (state.loading) {
    return (
      <div className="w-full bg-card rounded-lg shadow p-6" role="region" aria-label="Discovery Progress">
        <div className="text-center text-muted-foreground">Loading...</div>
      </div>
    );
  }
  
  // Error state
  if (state.error) {
    return (
      <div className="w-full bg-card rounded-lg shadow p-6" role="region" aria-label="Discovery Progress">
        <div className="text-center text-destructive">{state.error}</div>
      </div>
    );
  }
  
  if (!state.data) {
    return null;
  }
  
  return (
    <div className="w-full bg-card rounded-lg shadow p-6 mb-6" role="region" aria-label="Discovery Progress" data-testid="discovery-progress">
      <div className="flex items-center justify-between mb-4">
        <h2 className="text-lg font-semibold">Discovery Progress</h2>
        <PhaseIndicator phase={state.data.phase} />
      </div>
      
      <div className="space-y-4">
        {/* Success message - shown in any state */}
        {state.showSuccessMessage && (
          <div className="mt-4 p-3 rounded-lg border bg-success/10 border-success text-success" data-testid="success-message">
            Answer submitted! Loading next question...
          </div>
        )}
        
        {/* Idle State */}
        {state.isIdle && (
          <DiscoveryIdle
            projectId={projectId}
            isStarting={state.isStarting}
            startError={state.startError}
            onStartDiscovery={state.handleStartDiscovery}
          />
        )}
        
        {/* Discovering State */}
        {state.isDiscovering && state.data.discovery && (
          <>
            <DiscoveryQuestion
              question={state.data.discovery.current_question?.question || ''}
              category={state.data.discovery.current_question?.category || ''}
              questionIndex={state.data.discovery.answered_count + 1}
              totalQuestions={state.data.discovery.total_required}
              progressPercentage={state.data.discovery.progress_percentage}
              answeredCount={state.data.discovery.answered_count}
            />
            
            {/* Show stuck state or answer input */}
            {!state.data.discovery.current_question && !state.isLoadingNextQuestion && (
              <DiscoveryStuck
                onRestart={state.handleRestartDiscovery}
                isRestarting={state.isRestarting}
                restartError={state.restartError}
              />
            )}
            
            {state.data.discovery.current_question && !state.isLoadingNextQuestion && (
              <DiscoveryAnswer
                answer={state.answer}
                onAnswerChange={state.setAnswer}
                onSubmit={state.submitAnswer}
                onKeyPress={state.handleKeyPress}
                isSubmitting={state.isSubmitting}
                isLoadingNextQuestion={state.isLoadingNextQuestion}
                submissionError={state.submissionError}
                showSuccessMessage={state.showSuccessMessage}
              />
            )}
          </>
        )}
        
        {/* Completed State */}
        {state.isCompleted && (
          <DiscoveryComplete
            projectId={projectId}
            phase={state.data.phase}
            isSectionMinimized={state.isSectionMinimized}
            onMinimize={() => state.setIsSectionMinimized(true)}
            onExpand={() => state.setIsSectionMinimized(false)}
            isGeneratingPRD={state.isGeneratingPRD}
            prdCompleted={state.prdCompleted}
            prdError={state.prdError}
            prdStage={state.prdStage}
            prdMessage={state.prdMessage}
            prdProgressPct={state.prdProgressPct}
            isRetryingPrd={state.isRetryingPrd}
            onRetryPrd={state.handleRetryPrdGeneration}
            onViewPRD={onViewPRD}
            onRestart={state.handleRestartDiscovery}
            isRestarting={state.isRestarting}
            restartError={state.restartError}
            tasksGenerated={state.tasksGenerated}
            isGeneratingTasks={state.isGeneratingTasks}
            taskGenerationError={state.taskGenerationError}
            taskGenerationProgress={state.taskGenerationProgress}
            issuesCount={state.issuesCount}
            tasksCount={state.tasksCount}
            taskStateInitialized={state.taskStateInitialized}
            tasksAlreadyExistMessage={state.tasksAlreadyExistMessage}
            onGenerateTasks={state.handleGenerateTaskBreakdown}
            onNavigateToTasks={onNavigateToTasks}
          />
        )}
      </div>
    </div>
  );
});

DiscoveryProgress.displayName = 'DiscoveryProgress';
export default DiscoveryProgress;
```

### 6. Update Import Path

**Update `file:web-ui/src/components/DiscoveryProgress.tsx`** (original location)

Replace the entire file with a re-export to maintain backward compatibility:

```typescript
/**
 * DiscoveryProgress Component
 * 
 * Re-export from discovery/ subdirectory for backward compatibility.
 * The component has been refactored into focused sub-components.
 * 
 * @see web-ui/src/components/discovery/DiscoveryProgress.tsx
 */
export { default } from './discovery/DiscoveryProgress';
```

### 7. Update Test Files

**Update all test files in `file:web-ui/__tests__/components/`:**

- `DiscoveryProgress.test.tsx`
- `DiscoveryProgress.advanced.test.tsx`
- `DiscoveryProgress.answer.test.tsx`
- `DiscoveryProgress.core.test.tsx`
- `DiscoveryProgress.error.test.tsx`
- `DiscoveryProgress.prd.test.tsx`
- `DiscoveryProgress.progress.test.tsx`
- `DiscoveryProgress.websocket.test.tsx`

**Changes needed:**
1. Update import path from `@/components/DiscoveryProgress` to `@/components/discovery/DiscoveryProgress`
2. Add new test file `file:web-ui/__tests__/components/discovery/useDiscoveryState.test.tsx` for the custom hook
3. Optionally add unit tests for individual phase components (DiscoveryIdle, DiscoveryQuestion, etc.)
4. Verify all existing tests pass without modification (they should, as the container maintains the same data-testid attributes)

**Update `file:web-ui/__tests__/components/DiscoveryProgress.testutils.tsx`:**
- Update import path for DiscoveryProgress component
- No other changes needed as mocks remain the same

### 8. Verification Checklist

After implementation, verify:

1. **Line count targets:**
   - `DiscoveryProgress.tsx` (container): <300 lines ✓
   - `useDiscoveryState.ts`: ~400-500 lines
   - Each phase component: <150 lines
   - Total: ~1,200-1,300 lines (slight increase due to type definitions and imports, but much better organized)

2. **Functionality preservation:**
   - All 8 test suites pass without modification
   - WebSocket events handled correctly
   - State transitions work as before
   - No visual regressions (test with `data-testid` attributes)

3. **Code quality:**
   - All TypeScript types properly defined
   - No `any` types used
   - Proper use of `memo`, `useCallback`, `useMemo`
   - Consistent naming conventions
   - All imports use `@/` alias

4. **Performance:**
   - No unnecessary re-renders (use React DevTools Profiler)
   - WebSocket cleanup on unmount
   - Timer cleanup in useEffect hooks

## Component Interaction Flow

```mermaid
sequenceDiagram
    participant User
    participant Container as DiscoveryProgress<br/>(Container)
    participant Hook as useDiscoveryState<br/>(Hook)
    participant Idle as DiscoveryIdle
    participant Question as DiscoveryQuestion
    participant Answer as DiscoveryAnswer
    participant PRD as DiscoveryPRDGeneration
    participant Tasks as DiscoveryTaskGeneration
    participant WS as WebSocket

    User->>Container: Load component
    Container->>Hook: useDiscoveryState(projectId)
    Hook->>Hook: Fetch initial data
    Hook->>WS: Subscribe to events
    Hook-->>Container: Return state & handlers
    
    alt Idle State
        Container->>Idle: Render with handlers
        User->>Idle: Click "Start Discovery"
        Idle->>Hook: handleStartDiscovery()
        Hook->>WS: Start discovery
        WS-->>Hook: discovery_starting event
        Hook->>Hook: Update state
        Hook-->>Container: isDiscovering = true
    end
    
    alt Discovering State
        Container->>Question: Render progress
        Container->>Answer: Render input form
        User->>Answer: Type answer & submit
        Answer->>Hook: submitAnswer()
        Hook->>Hook: Validate & POST
        WS-->>Hook: question_ready event
        Hook->>Hook: Update question
        Hook-->>Container: New question data
        Container->>Question: Re-render with new question
    end
    
    alt Completed State
        WS-->>Hook: discovery_complete event
        Hook->>Hook: isCompleted = true
        Hook-->>Container: State update
        Container->>PRD: Render PRD generation
        WS-->>Hook: prd_generation_progress
        Hook-->>PRD: Update progress
        WS-->>Hook: prd_generation_completed
        Hook->>Hook: prdCompleted = true
        Hook-->>Container: State update
        Container->>Tasks: Render task generation
        User->>Tasks: Click "Generate Tasks"
        Tasks->>Hook: handleGenerateTaskBreakdown()
        WS-->>Hook: tasks_ready event
        Hook-->>Container: tasksGenerated = true
    end
```

## File Size Comparison

| Component | Before | After | Change |
|-----------|--------|-------|--------|
| DiscoveryProgress.tsx | 1,165 lines | ~250 lines | -915 lines (-78%) |
| useDiscoveryState.ts | - | ~450 lines | +450 lines (new) |
| DiscoveryIdle.tsx | - | ~40 lines | +40 lines (new) |
| DiscoveryQuestion.tsx | - | ~80 lines | +80 lines (new) |
| DiscoveryAnswer.tsx | - | ~120 lines | +120 lines (new) |
| DiscoveryStuck.tsx | - | ~60 lines | +60 lines (new) |
| DiscoveryPRDGeneration.tsx | - | ~150 lines | +150 lines (new) |
| DiscoveryTaskGeneration.tsx | - | ~140 lines | +140 lines (new) |
| DiscoveryMinimized.tsx | - | ~50 lines | +50 lines (new) |
| DiscoveryComplete.tsx | - | ~80 lines | +80 lines (new) |
| types.ts | - | ~100 lines | +100 lines (new) |
| **Total** | **1,165 lines** | **~1,520 lines** | **+355 lines (+30%)** |

The total line count increases due to:
- Type definitions and interfaces
- Import statements in each file
- Component boundaries and exports
- Improved code organization and readability

However, maintainability improves dramatically:
- Each file has a single, clear responsibility
- State logic is isolated and testable
- Components are reusable and composable
- Changes to one phase don't affect others

---

Execution Information

Branch: main
Commit: a107395

---

💡 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.

[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

#187 - refactor: Consolidate web-ui test files to tests/ directory [merged]
#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]
#256 - refactor(tests): split DiscoveryProgress tests into focused files [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]

Closing as part of v2 roadmap cleanup. This v1-specific issue is retained with the v1-legacy label as reference material for Phase 3 (Web UI rebuild). See the v2 strategic roadmap for current priorities.