[Phase 5.4] PRD stress-test web UI: results view and PRD refinement

[frankbria]

Goal

Render stress-test results as an interactive ambiguity review UI where users answer questions inline and submit answers to refine the PRD.

Background

Follows the trigger issue (#561). The stress-test produces a decomposition tree with ambiguities surfaced as questions. Users need to answer them in the browser to get a refined PRD.

Scope

Results view (shown after stress-test completes):

• Decomposition tree displayed as collapsible cards: top-level breakdown → leaf ambiguities
• Each ambiguity shown as a card with:
  • Question text (the ambiguity the agent cannot resolve)
  • Severity indicator (blocking / warning)
  • Inline text area for the user's answer
• "All answered" progress indicator (e.g., "4 of 7 answered")
• [Refine PRD] button — enabled when all blocking ambiguities are answered
  • Calls POST /api/v2/prd/stress-test/refine with the original PRD + answers
  • Streams the refined PRD back
  • On completion: saves the refined PRD and shows a diff/confirmation

Out of scope

• Re-running stress-test on the refined PRD (user can click [Stress Test] again)
• Non-blocking ambiguities are skippable

Acceptance criteria

• Ambiguity cards render with question text and answer fields
• [Refine PRD] is disabled until all blocking questions answered
• Refined PRD saves and is visible in the PRD editor
• npm test and uv run pytest pass

[coderabbitai]

🔗 Related PRs

#194 - Fix PRD generation progress tracking UI [merged]
#317 - feat(cli): add interactive PRD generation via Socratic discovery [merged]
#390 - feat: Blocker Resolution View - Answer Agent Questions [merged]
#446 - feat(prd): recursive decomposition stress test (#421) [merged]
#495 - feat(web-ui): blocker lifecycle explanation and recovery guidance (#473) [merged]
#525 - feat(web-ui): PRD version history panel with diff and restore [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 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!

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The codebase has a clear layered architecture: FastAPI backend (codeframe/ui/routers/) + Next.js 19 frontend (web-ui/src/). The stress-test core logic (codeframe/core/prd_stress_test.py) is complete with StressTestResult, DecompositionNode, Ambiguity, and resolve_ambiguities_into_prd. The PRD page (web-ui/src/app/prd/page.tsx) renders PRDView with a PRDHeader action bar. No stress-test HTTP endpoint or UI exists yet. The existing prdApi.createVersion in file:web-ui/src/lib/api.ts is the right mechanism to save the refined PRD. The Ambiguity model has no severity field — the issue calls for blocking/warning severity, so this must be added. Streaming is done via SSE (useEventSource / useTaskStream), but the refine endpoint can return a plain streaming response since the refined PRD is a single text blob.

Approach

Add a severity field to Ambiguity, expose two new FastAPI endpoints on the existing prd_v2 router (POST /api/v2/prd/stress-test and POST /api/v2/prd/stress-test/refine), add corresponding TypeScript types and API client methods, then build the UI as a panel inside the existing PRD page — mirroring the DiscoveryPanel pattern — with an AmbiguityCard list, progress indicator, and Refine PRD button.

---

Implementation Steps

1. Extend Ambiguity with severity

File: file:codeframe/core/prd_stress_test.py

• Add a severity field to the Ambiguity dataclass with type str and default "blocking".
• In classify_and_decompose, read data.get("severity", "blocking") from the LLM JSON response and assign it to the new field.
• Update CLASSIFY_AND_DECOMPOSE_SYSTEM prompt to instruct the LLM to include "severity": "blocking" | "warning" in the ambiguous-node JSON.

---

2. Add Pydantic models and two new endpoints to prd_v2 router

File: file:codeframe/ui/routers/prd_v2.py

Add the following Pydantic models:

Model	Fields
AmbiguityResponse	id, label, source_node_title, questions: list[str], recommendation, severity, resolved_answer: str | None
DecompositionNodeResponse	id, title, description, classification, children: list[Self], depth, complexity_hint, ambiguity_id: str | None
StressTestResponse	prd_title, tree: list[DecompositionNodeResponse], ambiguities: list[AmbiguityResponse], ambiguity_report
RefineRequest	prd_id, answers: list[{ambiguity_id: str, answer: str}]

Endpoint 1 — trigger stress-test:

POST /api/v2/prd/stress-test

• Query param: workspace_path
• Body: optional prd_id (defaults to latest)
• Calls stress_test_prd(record.content, provider) from codeframe.core.prd_stress_test
• Returns StressTestResponse (synchronous — the LLM calls are already batched inside stress_test_prd)
• Use @rate_limit_ai() decorator (matching the pattern in discovery_v2.py)
• Instantiate AnthropicProvider the same way the CLI does in codeframe/cli/app.py

Endpoint 2 — refine PRD:

POST /api/v2/prd/stress-test/refine

• Body: RefineRequest
• Resolves answers into Ambiguity objects, calls resolve_ambiguities_into_prd, then calls prd.create_new_version with change_summary="Refined via stress-test ambiguity resolution"
• Returns the new PrdResponse (reuse _prd_to_response)

Route ordering note: Register /stress-test and /stress-test/refine before the /{prd_id} catch-all route to avoid FastAPI matching them as IDs.

---

3. Add TypeScript types

File: file:web-ui/src/types/prd.ts

Add:

AmbiguityItem { id, label, source_node_title, questions, recommendation, severity, resolved_answer }
DecompositionNodeItem { id, title, description, classification, children, depth, complexity_hint, ambiguity_id }
StressTestResponse { prd_title, tree, ambiguities, ambiguity_report }

---

4. Add API client methods

File: file:web-ui/src/lib/api.ts

Extend prdApi with:

• stressTest(workspacePath, prdId?) → POST /api/v2/prd/stress-test → StressTestResponse
• refine(workspacePath, prdId, answers) → POST /api/v2/prd/stress-test/refine → PrdResponse

---

5. Build AmbiguityCard component

New file: file:web-ui/src/components/prd/AmbiguityCard.tsx

Props: ambiguity: AmbiguityItem, answer: string, onChange(id, answer): void

• Renders the label as a card title
• Lists each question in questions as bullet points
• Shows a severity badge: destructive style for "blocking", warning/muted style for "warning" — using existing Tailwind classes (no new dependencies)
• Renders a <textarea> bound to answer / onChange
• Shows recommendation as helper text below the textarea

---

6. Build StressTestPanel component

New file: file:web-ui/src/components/prd/StressTestPanel.tsx

State: answers: Record<string, string> (keyed by ambiguity.id), isRefining: boolean

Logic:

• Receives result: StressTestResponse, workspacePath, prdId, onRefined(prd: PrdResponse): void, onClose(): void
• Computes blockingUnanswered = count of ambiguities where severity === "blocking" and answers[id] is empty
• Renders a progress indicator: "X of Y answered" (count all ambiguities with non-empty answers)
• Renders AmbiguityCard for each ambiguity in result.ambiguities
• [Refine PRD] button: disabled when blockingUnanswered > 0 or isRefining; on click calls prdApi.refine(...) then onRefined(newPrd)
• Uses sonner toast for error feedback (matching existing pattern)

---

7. Wire stress-test into PRDView and PRDHeader

File: file:web-ui/src/components/prd/PRDHeader.tsx

• Add onStressTest?: () => void and isStressTesting?: boolean props
• Add a [Stress Test] button (use a suitable icon from @hugeicons/react, e.g. TestTube01Icon or FlaskIcon) next to the existing action buttons; disabled when !prd || isStressTesting

File: file:web-ui/src/components/prd/PRDView.tsx

• Add props: stressTestResult: StressTestResponse | null, isStressTesting: boolean, onStressTest: () => void, onStressTestRefined: (prd: PrdResponse) => void, onCloseStressTest: () => void
• Pass onStressTest / isStressTesting down to PRDHeader
• When stressTestResult is non-null, render StressTestPanel in a third column (or below the editor) — use the same responsive grid pattern already used for DiscoveryPanel

---

8. Wire state into PrdPage

File: file:web-ui/src/app/prd/page.tsx

• Add state: isStressTesting: boolean, stressTestResult: StressTestResponse | null
• handleStressTest: sets isStressTesting = true, calls prdApi.stressTest(workspacePath, prd.id), stores result in stressTestResult, resets isStressTesting; shows toast.error on failure
• handleStressTestRefined(newPrd): calls mutatePrd(newPrd, false), clears stressTestResult
• Pass all new props to PRDView

---

Data flow diagram

sequenceDiagram
    participant User
    participant PrdPage
    participant prdApi
    participant Backend
    participant StressTestPanel

    User->>PrdPage: clicks [Stress Test]
    PrdPage->>prdApi: stressTest(workspacePath, prdId)
    prdApi->>Backend: POST /api/v2/prd/stress-test
    Backend-->>prdApi: StressTestResponse (tree + ambiguities)
    prdApi-->>PrdPage: StressTestResponse
    PrdPage->>StressTestPanel: render with result

    User->>StressTestPanel: fills answers for blocking ambiguities
    StressTestPanel->>StressTestPanel: enables [Refine PRD] button
    User->>StressTestPanel: clicks [Refine PRD]
    StressTestPanel->>prdApi: refine(workspacePath, prdId, answers)
    prdApi->>Backend: POST /api/v2/prd/stress-test/refine
    Backend-->>prdApi: PrdResponse (new version)
    prdApi-->>StressTestPanel: PrdResponse
    StressTestPanel->>PrdPage: onRefined(newPrd)
    PrdPage->>PrdPage: mutatePrd(newPrd) — PRD editor updates

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a clear layered architecture: FastAPI backend (`codeframe/ui/routers/`) + Next.js 19 frontend (`web-ui/src/`). The stress-test core logic (`codeframe/core/prd_stress_test.py`) is complete with `StressTestResult`, `DecompositionNode`, `Ambiguity`, and `resolve_ambiguities_into_prd`. The PRD page (`web-ui/src/app/prd/page.tsx`) renders `PRDView` with a `PRDHeader` action bar. No stress-test HTTP endpoint or UI exists yet. The existing `prdApi.createVersion` in `file:web-ui/src/lib/api.ts` is the right mechanism to save the refined PRD. The `Ambiguity` model has no `severity` field — the issue calls for blocking/warning severity, so this must be added. Streaming is done via SSE (`useEventSource` / `useTaskStream`), but the refine endpoint can return a plain streaming response since the refined PRD is a single text blob.

## Approach

Add a `severity` field to `Ambiguity`, expose two new FastAPI endpoints on the existing `prd_v2` router (`POST /api/v2/prd/stress-test` and `POST /api/v2/prd/stress-test/refine`), add corresponding TypeScript types and API client methods, then build the UI as a panel inside the existing PRD page — mirroring the `DiscoveryPanel` pattern — with an `AmbiguityCard` list, progress indicator, and **Refine PRD** button.

---

## Implementation Steps

### 1. Extend `Ambiguity` with severity

**File:** `file:codeframe/core/prd_stress_test.py`

- Add a `severity` field to the `Ambiguity` dataclass with type `str` and default `"blocking"`.
- In `classify_and_decompose`, read `data.get("severity", "blocking")` from the LLM JSON response and assign it to the new field.
- Update `CLASSIFY_AND_DECOMPOSE_SYSTEM` prompt to instruct the LLM to include `"severity": "blocking" | "warning"` in the ambiguous-node JSON.

---

### 2. Add Pydantic models and two new endpoints to `prd_v2` router

**File:** `file:codeframe/ui/routers/prd_v2.py`

Add the following Pydantic models:

| Model | Fields |
|---|---|
| `AmbiguityResponse` | `id`, `label`, `source_node_title`, `questions: list[str]`, `recommendation`, `severity`, `resolved_answer: str \| None` |
| `DecompositionNodeResponse` | `id`, `title`, `description`, `classification`, `children: list[Self]`, `depth`, `complexity_hint`, `ambiguity_id: str \| None` |
| `StressTestResponse` | `prd_title`, `tree: list[DecompositionNodeResponse]`, `ambiguities: list[AmbiguityResponse]`, `ambiguity_report` |
| `RefineRequest` | `prd_id`, `answers: list[{ambiguity_id: str, answer: str}]` |

**Endpoint 1 — trigger stress-test:**

```
POST /api/v2/prd/stress-test
```
- Query param: `workspace_path`
- Body: optional `prd_id` (defaults to latest)
- Calls `stress_test_prd(record.content, provider)` from `codeframe.core.prd_stress_test`
- Returns `StressTestResponse` (synchronous — the LLM calls are already batched inside `stress_test_prd`)
- Use `@rate_limit_ai()` decorator (matching the pattern in `discovery_v2.py`)
- Instantiate `AnthropicProvider` the same way the CLI does in `codeframe/cli/app.py`

**Endpoint 2 — refine PRD:**

```
POST /api/v2/prd/stress-test/refine
```
- Body: `RefineRequest`
- Resolves answers into `Ambiguity` objects, calls `resolve_ambiguities_into_prd`, then calls `prd.create_new_version` with `change_summary="Refined via stress-test ambiguity resolution"`
- Returns the new `PrdResponse` (reuse `_prd_to_response`)

> **Route ordering note:** Register `/stress-test` and `/stress-test/refine` **before** the `/{prd_id}` catch-all route to avoid FastAPI matching them as IDs.

---

### 3. Add TypeScript types

**File:** `file:web-ui/src/types/prd.ts`

Add:

```ts
AmbiguityItem { id, label, source_node_title, questions, recommendation, severity, resolved_answer }
DecompositionNodeItem { id, title, description, classification, children, depth, complexity_hint, ambiguity_id }
StressTestResponse { prd_title, tree, ambiguities, ambiguity_report }
```

---

### 4. Add API client methods

**File:** `file:web-ui/src/lib/api.ts`

Extend `prdApi` with:

- `stressTest(workspacePath, prdId?)` → `POST /api/v2/prd/stress-test` → `StressTestResponse`
- `refine(workspacePath, prdId, answers)` → `POST /api/v2/prd/stress-test/refine` → `PrdResponse`

---

### 5. Build `AmbiguityCard` component

**New file:** `file:web-ui/src/components/prd/AmbiguityCard.tsx`

Props: `ambiguity: AmbiguityItem`, `answer: string`, `onChange(id, answer): void`

- Renders the `label` as a card title
- Lists each question in `questions` as bullet points
- Shows a severity badge: destructive style for `"blocking"`, warning/muted style for `"warning"` — using existing Tailwind classes (no new dependencies)
- Renders a `<textarea>` bound to `answer` / `onChange`
- Shows `recommendation` as helper text below the textarea

---

### 6. Build `StressTestPanel` component

**New file:** `file:web-ui/src/components/prd/StressTestPanel.tsx`

State: `answers: Record<string, string>` (keyed by `ambiguity.id`), `isRefining: boolean`

Logic:
- Receives `result: StressTestResponse`, `workspacePath`, `prdId`, `onRefined(prd: PrdResponse): void`, `onClose(): void`
- Computes `blockingUnanswered` = count of ambiguities where `severity === "blocking"` and `answers[id]` is empty
- Renders a progress indicator: `"X of Y answered"` (count all ambiguities with non-empty answers)
- Renders `AmbiguityCard` for each ambiguity in `result.ambiguities`
- **[Refine PRD]** button: disabled when `blockingUnanswered > 0` or `isRefining`; on click calls `prdApi.refine(...)` then `onRefined(newPrd)`
- Uses `sonner` `toast` for error feedback (matching existing pattern)

---

### 7. Wire stress-test into `PRDView` and `PRDHeader`

**File:** `file:web-ui/src/components/prd/PRDHeader.tsx`

- Add `onStressTest?: () => void` and `isStressTesting?: boolean` props
- Add a **[Stress Test]** button (use a suitable icon from `@hugeicons/react`, e.g. `TestTube01Icon` or `FlaskIcon`) next to the existing action buttons; disabled when `!prd || isStressTesting`

**File:** `file:web-ui/src/components/prd/PRDView.tsx`

- Add props: `stressTestResult: StressTestResponse | null`, `isStressTesting: boolean`, `onStressTest: () => void`, `onStressTestRefined: (prd: PrdResponse) => void`, `onCloseStressTest: () => void`
- Pass `onStressTest` / `isStressTesting` down to `PRDHeader`
- When `stressTestResult` is non-null, render `StressTestPanel` in a third column (or below the editor) — use the same responsive grid pattern already used for `DiscoveryPanel`

---

### 8. Wire state into `PrdPage`

**File:** `file:web-ui/src/app/prd/page.tsx`

- Add state: `isStressTesting: boolean`, `stressTestResult: StressTestResponse | null`
- `handleStressTest`: sets `isStressTesting = true`, calls `prdApi.stressTest(workspacePath, prd.id)`, stores result in `stressTestResult`, resets `isStressTesting`; shows `toast.error` on failure
- `handleStressTestRefined(newPrd)`: calls `mutatePrd(newPrd, false)`, clears `stressTestResult`
- Pass all new props to `PRDView`

---

### Data flow diagram

```mermaid
sequenceDiagram
    participant User
    participant PrdPage
    participant prdApi
    participant Backend
    participant StressTestPanel

    User->>PrdPage: clicks [Stress Test]
    PrdPage->>prdApi: stressTest(workspacePath, prdId)
    prdApi->>Backend: POST /api/v2/prd/stress-test
    Backend-->>prdApi: StressTestResponse (tree + ambiguities)
    prdApi-->>PrdPage: StressTestResponse
    PrdPage->>StressTestPanel: render with result

    User->>StressTestPanel: fills answers for blocking ambiguities
    StressTestPanel->>StressTestPanel: enables [Refine PRD] button
    User->>StressTestPanel: clicks [Refine PRD]
    StressTestPanel->>prdApi: refine(workspacePath, prdId, answers)
    prdApi->>Backend: POST /api/v2/prd/stress-test/refine
    Backend-->>prdApi: PrdResponse (new version)
    prdApi-->>StressTestPanel: PrdResponse
    StressTestPanel->>PrdPage: onRefined(newPrd)
    PrdPage->>PrdPage: mutatePrd(newPrd) — PRD editor updates
```

---

Execution Information

Branch: main
Commit: 3f14270

---

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