docs: add frontend gap cards optimization plan

4-task plan: add severity to backend model, rewrite renderQuestionCards
with generic rendering and severity support, simplify gapSubmitAll.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/superpowers/plans/2026-04-13-frontend-gap-cards.md

@@ -0,0 +1,340 @@
+# Frontend Gap Cards Optimization Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the frontend question cards a generic severity-aware renderer with no hardcoded category knowledge, letting the backend own all state mapping.
+
+**Architecture:** Add `severity` field to `GeneratedQuestionCard` backend model. Rewrite frontend `renderQuestionCards()` to render all categories generically with severity indicators. Simplify `gapSubmitAll()` to just compose and send a message with no local state updates. Delete `gapDimChanged()`.
+
+**Tech Stack:** Vanilla JS (no build step), Pydantic models, pytest
+
+---
+
+### File Structure
+
+| File | Action | Responsibility |
+|------|--------|----------------|
+| `agents/gap_analyzer.py` | Modify | Add `severity` field to `GeneratedQuestionCard`, update system prompt |
+| `tests/test_gap_analyzer.py` | Modify | Update model tests for new severity field |
+| `web/index.html` | Modify | Rewrite card rendering, simplify submit, add severity CSS, delete dimension handler |
+
+---
+
+### Task 1: Add severity field to GeneratedQuestionCard
+
+**Files:**
+- Modify: `agents/gap_analyzer.py:31-39`
+- Modify: `agents/gap_analyzer.py:55-74` (system prompt)
+- Test: `tests/test_gap_analyzer.py`
+
+- [ ] **Step 1: Write failing test for severity on question card**
+
+Add to `tests/test_gap_analyzer.py` inside `TestModels`, after the existing `test_generated_question_card_defaults` test:
+
+```python
+    def test_question_card_severity_default(self):
+        card = GeneratedQuestionCard(
+            category="material",
+            question="What material?",
+            responsible_agent="engineering",
+        )
+        assert card.severity == "recommended"
+
+    def test_question_card_severity_blocking(self):
+        card = GeneratedQuestionCard(
+            category="material",
+            question="What material?",
+            responsible_agent="engineering",
+            severity="blocking",
+        )
+        assert card.severity == "blocking"
+
+    def test_question_card_severity_validation(self):
+        import pytest
+        with pytest.raises(Exception):
+            GeneratedQuestionCard(
+                category="x",
+                question="q",
+                responsible_agent="design",
+                severity="invalid",
+            )
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest tests/test_gap_analyzer.py::TestModels::test_question_card_severity_default tests/test_gap_analyzer.py::TestModels::test_question_card_severity_blocking tests/test_gap_analyzer.py::TestModels::test_question_card_severity_validation -v`
+Expected: FAIL — `severity` field doesn't exist on `GeneratedQuestionCard`.
+
+- [ ] **Step 3: Add severity field to GeneratedQuestionCard**
+
+In `agents/gap_analyzer.py`, add the `severity` field to `GeneratedQuestionCard` (line 31-39). The field goes after `agent_color`:
+
+Old:
+```python
+class GeneratedQuestionCard(BaseModel):
+    """A contextual question card for the UI, generated by the LLM."""
+    category: str
+    question: str
+    responsible_agent: str
+    agent_name: str = ""
+    agent_color: str = ""
+    suggestions: list[str] = Field(default_factory=list)
+    allow_custom: bool = True
+```
+
+New:
+```python
+class GeneratedQuestionCard(BaseModel):
+    """A contextual question card for the UI, generated by the LLM."""
+    category: str
+    question: str
+    responsible_agent: str
+    agent_name: str = ""
+    agent_color: str = ""
+    severity: Literal["blocking", "recommended", "nice_to_have"] = "recommended"
+    suggestions: list[str] = Field(default_factory=list)
+    allow_custom: bool = True
+```
+
+- [ ] **Step 4: Update system prompt to set severity on cards**
+
+In `agents/gap_analyzer.py`, in the `_SYSTEM_PROMPT` string, after the line `- If no gaps exist, return has_gaps: false with empty lists.`, add:
+
+```
+- Set severity on each question card matching the gap it addresses.
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `uv run pytest tests/test_gap_analyzer.py -v`
+Expected: PASS (all 13 tests — 8 existing + 3 new)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add agents/gap_analyzer.py tests/test_gap_analyzer.py
+git commit -m "feat: add severity field to GeneratedQuestionCard"
+```
+
+---
+
+### Task 2: Rewrite frontend renderQuestionCards with severity support
+
+**Files:**
+- Modify: `web/index.html:1361-1408` (CSS)
+- Modify: `web/index.html:2169-2201` (renderQuestionCards function)
+
+- [ ] **Step 1: Add severity CSS rules**
+
+In `web/index.html`, after the existing `.gap-card-submit` rule (line 1408), add these new rules before the `/* ---- RESPONSIVE ---- */` comment:
+
+```css
+  .gap-card[data-severity="blocking"] {
+    border-left-color: var(--error);
+  }
+  .gap-card[data-severity="nice_to_have"] {
+    opacity: 0.7;
+  }
+  .gap-card-badge {
+    font-family: var(--font-mono);
+    font-size: 9px;
+    font-weight: 700;
+    color: var(--error);
+    margin-left: 6px;
+    text-transform: uppercase;
+  }
+```
+
+- [ ] **Step 2: Add buildGapTitle helper function**
+
+In `web/index.html`, replace line 2169 (`function renderQuestionCards(cards) {`) and the entire function body through line 2201 with the new implementation. First, add the helper right before `renderQuestionCards` (after line 2167 `let gapSelections = {};`):
+
+```javascript
+function buildGapTitle(cards) {
+  const counts = { blocking: 0, recommended: 0, nice_to_have: 0 };
+  for (const c of cards) counts[c.severity || 'recommended']++;
+  const parts = [];
+  if (counts.blocking) parts.push(counts.blocking + ' REQUIRED');
+  if (counts.recommended) parts.push(counts.recommended + ' RECOMMENDED');
+  if (counts.nice_to_have) parts.push(counts.nice_to_have + ' OPTIONAL');
+  return parts.join(', ');
+}
+```
+
+- [ ] **Step 3: Rewrite renderQuestionCards function**
+
+Replace the entire `renderQuestionCards` function (lines 2169-2201) with:
+
+```javascript
+function renderQuestionCards(cards) {
+  if (!cards || cards.length === 0) return '';
+  gapSelections = {};
+
+  // Sort by severity: blocking first, recommended second, nice_to_have last
+  const order = { blocking: 0, recommended: 1, nice_to_have: 2 };
+  const sorted = [...cards].sort((a, b) => (order[a.severity] || 1) - (order[b.severity] || 1));
+
+  let html = '<div class="gap-cards" id="active-gap-cards">';
+  html += '<div class="gap-cards-title">' + escapeHtml(buildGapTitle(sorted)) + '</div>';
+
+  for (const card of sorted) {
+    const sev = card.severity || 'recommended';
+    html += '<div class="gap-card" style="border-left-color:' + (sev === 'blocking' ? 'var(--error)' : sev === 'nice_to_have' ? 'var(--border)' : escapeHtml(card.agent_color)) + ';" data-category="' + escapeHtml(card.category) + '" data-severity="' + escapeHtml(sev) + '">';
+
+    // Header
+    html += '<div class="gap-card-header">';
+    html += '<div class="gap-card-dot" style="background:' + escapeHtml(card.agent_color) + ';"></div>';
+    html += '<span class="gap-card-agent">' + escapeHtml(card.agent_name) + '</span>';
+    if (sev === 'blocking') html += '<span class="gap-card-badge">REQUIRED</span>';
+    html += '</div>';
+
+    // Question
+    html += '<div class="gap-card-question">' + escapeHtml(card.question) + '</div>';
+
+    // Generic input: chips + optional custom
+    if (card.suggestions && card.suggestions.length > 0) {
+      html += '<div class="wizard-chips">';
+      for (const s of card.suggestions) {
+        html += '<button class="wizard-chip" onclick="gapToggleChip(this,\'' + escapeHtml(s) + '\',\'' + escapeHtml(card.category) + '\')">' + escapeHtml(s) + '</button>';
+      }
+      html += '</div>';
+    }
+    if (card.allow_custom) {
+      html += '<input class="wizard-input" placeholder="Type your answer..." onchange="gapSetCustom(this.value,\'' + escapeHtml(card.category) + '\')">';
+    }
+
+    html += '</div>';
+  }
+
+  html += '<button class="gap-card-submit" onclick="gapSubmitAll()" style="width:100%;margin-top:4px;">Submit</button>';
+  html += '</div>';
+  return html;
+}
+```
+
+Key changes from old version:
+- No `category === 'dimension'` special case
+- Sorts cards by severity
+- Sets `data-severity` attribute on each card
+- Blocking cards get red border via inline style + "REQUIRED" badge
+- Nice-to-have cards get dim border color
+- Custom input shown whenever `allow_custom` is true (independent of suggestions)
+- Chips and custom input are not mutually exclusive — both can appear
+
+- [ ] **Step 4: Verify by inspecting the code**
+
+Read the rewritten function to confirm:
+- No reference to `'dimension'` category
+- `data-severity` attribute is set
+- `buildGapTitle()` is called
+- Severity-based border color logic is correct
+- `escapeHtml()` used on all dynamic content
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/index.html
+git commit -m "feat: rewrite renderQuestionCards with severity support and generic rendering"
+```
+
+---
+
+### Task 3: Simplify gapSubmitAll and delete gapDimChanged
+
+**Files:**
+- Modify: `web/index.html:2227-2274` (gapDimChanged + gapSubmitAll)
+
+- [ ] **Step 1: Delete gapDimChanged function**
+
+Delete the entire `gapDimChanged` function (lines 2227-2237):
+
+```javascript
+function gapDimChanged() {
+  const w = document.getElementById('gap-dim-width')?.value;
+  const h = document.getElementById('gap-dim-height')?.value;
+  const d = document.getElementById('gap-dim-depth')?.value;
+  const parts = [];
+  if (w) parts.push(w + 'mm wide');
+  if (h) parts.push(h + 'mm high');
+  if (d) parts.push(d + 'mm deep');
+  if (parts.length > 0) gapSelections['dimension'] = parts.join(', ');
+  else delete gapSelections['dimension'];
+}
+```
+
+- [ ] **Step 2: Replace gapSubmitAll function**
+
+Replace the entire `gapSubmitAll` function (lines 2239-2274) with:
+
+```javascript
+function gapSubmitAll() {
+  const parts = [];
+  for (const [category, value] of Object.entries(gapSelections)) {
+    if (value) {
+      const label = category.replace(/_/g, ' ');
+      parts.push(label + ': ' + value);
+    }
+  }
+  if (parts.length === 0) return;
+  removeGapCards();
+  sendMessage(parts.join(', '));
+}
+```
+
+Key changes:
+- No `gapDimChanged()` call
+- No `designState` mutations (no `designState.material = ...`, no dimension parsing, etc.)
+- No `saveState()` call
+- Formats as `"category label: value"` with snake_case converted to spaces
+- Just sends the message — backend handles state updates
+
+- [ ] **Step 3: Remove stale CSS for dimension inputs in gap cards**
+
+In `web/index.html`, delete line 1401:
+
+```css
+  .gap-card .wizard-dim-row { margin-top: 4px; }
+```
+
+The `.wizard-dim-row` class is still used by the Guided wizard tab, so only remove the `.gap-card .wizard-dim-row` scoped rule.
+
+- [ ] **Step 4: Verify no remaining references to gapDimChanged**
+
+Search the file for `gapDimChanged` — should find zero results. Also search for `gap-dim-width`, `gap-dim-height`, `gap-dim-depth` — should find zero results (they were only in the deleted dimension rendering and `gapDimChanged`).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/index.html
+git commit -m "refactor: simplify gapSubmitAll, remove category-specific state mappings"
+```
+
+---
+
+### Task 4: Final verification
+
+**Files:**
+- All modified files
+
+- [ ] **Step 1: Run full backend test suite**
+
+Run: `uv run pytest tests/ -v`
+Expected: All tests PASS (275+ tests)
+
+- [ ] **Step 2: Verify frontend file is valid**
+
+Run: `grep -c 'gapDimChanged' web/index.html` — expected: `0`
+Run: `grep -c 'gap-dim-width' web/index.html` — expected: `0`
+Run: `grep -c "category === 'dimension'" web/index.html` — expected: `0`
+Run: `grep -c 'designState.material' web/index.html` — should NOT appear inside `gapSubmitAll` (may appear elsewhere in file for other features)
+Run: `grep -c 'buildGapTitle' web/index.html` — expected: `2` (definition + call)
+Run: `grep -c 'data-severity' web/index.html` — expected: at least `3` (JS + CSS)
+
+- [ ] **Step 3: Commit final state if any cleanup needed**
+
+If all checks pass and no cleanup needed, skip this step. Otherwise:
+
+```bash
+git add -A
+git commit -m "fix: cleanup from frontend gap cards verification"
+```