docs: implementation plan for AI interpretation visual differentiation

6-task plan: theme tokens, ai_badge/interpretation_card helpers,
tension_card and quality_signal_chip updates, verdict.py and mda.py rendering.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/superpowers/plans/2026-05-07-interpretation-visual.md

@@ -0,0 +1,589 @@
+# Interpretation Visual Differentiation — 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:** Visually distinguish AI-interpreted fields from sourced facts across the Primer dashboard using a purple left-border + tinted background + "✦ AI" badge system.
+
+**Architecture:** Pure frontend change. Add 4 color tokens to `theme.py`, add two HTML-helper functions to `components.py`, update the rendering of 2 fields in `verdict.py`, 1 field in `mda.py`, and modify 2 existing component functions (`tension_card`, `quality_signal_chip`). No schema or agent changes.
+
+**Tech Stack:** Streamlit, Python f-strings for HTML, pytest for unit tests on string-returning helpers.
+
+---
+
+## File Map
+
+| File | Change |
+|------|--------|
+| `dashboard/theme.py` | Add `AI_BG`, `AI_BORDER`, `AI_COLOR`, `AI_BADGE_BG` tokens |
+| `dashboard/components.py` | Add `ai_badge()`, `interpretation_card()`; modify `tension_card()`, `quality_signal_chip()` |
+| `dashboard/verdict.py` | Use `interpretation_card()` for `what_matters_most` and `non_obvious_takeaway` |
+| `dashboard/mda.py` | Use `interpretation_card()` for `language_shift` |
+| `tests/test_dashboard_components.py` | New file — unit tests for the new and modified helpers |
+
+---
+
+### Task 1: Add AI color tokens to `theme.py`
+
+**Files:**
+- Modify: `dashboard/theme.py`
+
+- [ ] **Step 1: Add the 4 new tokens after the existing `PURPLE` line**
+
+In `dashboard/theme.py`, find the line `PURPLE = "#8b5cf6"` (currently line 42) and add the four tokens immediately after it:
+
+```python
+PURPLE = "#8b5cf6"
+AI_BG      = "#faf5ff"
+AI_BORDER  = "#ddd6fe"
+AI_COLOR   = "#7c3aed"
+AI_BADGE_BG = "#ede9fe"
+```
+
+- [ ] **Step 2: Verify the file is syntactically valid**
+
+```bash
+python -c "from dashboard.theme import AI_BG, AI_BORDER, AI_COLOR, AI_BADGE_BG; print(AI_BG)"
+```
+
+Expected output: `#faf5ff`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add dashboard/theme.py
+git commit -m "feat: add AI interpretation color tokens to theme"
+```
+
+---
+
+### Task 2: Add `ai_badge()` and `interpretation_card()` helpers + write tests
+
+**Files:**
+- Modify: `dashboard/components.py`
+- Create: `tests/test_dashboard_components.py`
+
+- [ ] **Step 1: Write failing tests first**
+
+Create `tests/test_dashboard_components.py`:
+
+```python
+"""Unit tests for dashboard/components.py HTML helpers."""
+from __future__ import annotations
+import pytest
+from unittest.mock import patch, MagicMock
+
+
+def test_ai_badge_default_label():
+    from dashboard.components import ai_badge
+    html = ai_badge()
+    assert "✦ AI Synthesis" in html
+    assert "#7c3aed" in html
+    assert "#ede9fe" in html
+
+
+def test_ai_badge_custom_label():
+    from dashboard.components import ai_badge
+    html = ai_badge("AI")
+    assert "✦ AI" in html
+    assert "#7c3aed" in html
+
+
+def test_interpretation_card_contains_badge_and_content():
+    from dashboard.components import interpretation_card
+    html = interpretation_card("What matters most", "<p>Some insight</p>")
+    assert "✦ AI Synthesis" in html
+    assert "#8b5cf6" in html   # purple border
+    assert "#faf5ff" in html   # purple tint background
+    assert "What matters most" in html
+    assert "<p>Some insight</p>" in html
+
+
+def test_interpretation_card_custom_badge_label():
+    from dashboard.components import interpretation_card
+    html = interpretation_card("Language shift", "<p>tone changed</p>", badge_label="AI")
+    assert "✦ AI" in html
+    assert "Language shift" in html
+```
+
+- [ ] **Step 2: Run tests to confirm they fail**
+
+```bash
+python -m pytest tests/test_dashboard_components.py -v
+```
+
+Expected: `ImportError` or `AttributeError` — `ai_badge` not yet defined.
+
+- [ ] **Step 3: Add the imports and helpers to `dashboard/components.py`**
+
+At the top of `dashboard/components.py`, extend the theme import to include the new tokens:
+
+```python
+from dashboard.theme import (
+    GREEN, RED, AMBER, GRAY, BORDER, TEXT_FAINT,
+    BG, BG_MUTED, TEXT, TEXT_MUTED,
+    WARN_BG, WARN_BORDER,
+    BULL_BG, BULL_BORDER, BEAR_BG, BEAR_BORDER,
+    PURPLE, AI_BG, AI_BORDER, AI_COLOR, AI_BADGE_BG,
+)
+```
+
+Then add both helpers immediately after the existing `reliability_badge` function (after line 19):
+
+```python
+# ── AI interpretation badge ───────────────────────────────────────────────────
+
+def ai_badge(label: str = "AI Synthesis") -> str:
+    return (
+        f'<span style="background:{AI_BADGE_BG};color:{AI_COLOR};'
+        f'border:1px solid {AI_BORDER};border-radius:4px;'
+        f'padding:1px 7px;font-size:0.62rem;font-weight:600;">✦ {label}</span>'
+    )
+
+
+# ── AI interpretation card wrapper ────────────────────────────────────────────
+
+def interpretation_card(
+    header_label: str,
+    content_html: str,
+    badge_label: str = "AI Synthesis",
+) -> str:
+    return (
+        f'<div class="primer-card" style="background:{AI_BG};border:1px solid {BORDER};'
+        f'border-left:4px solid {PURPLE};border-radius:0 12px 12px 0;'
+        f'padding:20px 24px;margin-bottom:4px;">'
+        f'<div style="display:flex;align-items:center;gap:8px;margin-bottom:8px;">'
+        f'<span style="font-size:0.62rem;font-weight:700;letter-spacing:0.1em;'
+        f'text-transform:uppercase;color:{TEXT_MUTED};">{header_label}</span>'
+        f'{ai_badge(badge_label)}'
+        f'</div>'
+        f'{content_html}'
+        f'</div>'
+    )
+```
+
+- [ ] **Step 4: Run tests — expect pass**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_ai_badge_default_label tests/test_dashboard_components.py::test_ai_badge_custom_label tests/test_dashboard_components.py::test_interpretation_card_contains_badge_and_content tests/test_dashboard_components.py::test_interpretation_card_custom_badge_label -v
+```
+
+Expected: 4 PASSED
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dashboard/components.py tests/test_dashboard_components.py
+git commit -m "feat: add ai_badge and interpretation_card helpers"
+```
+
+---
+
+### Task 3: Update `tension_card()` — add AI badge to reading labels
+
+**Files:**
+- Modify: `dashboard/components.py` (the `tension_card` function, lines ~116–172)
+
+The tension card panels keep their green/red backgrounds (they provide bull/bear orientation). We only add a micro "✦ AI" badge next to the "Surface reading" and "Deeper reading" labels.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_dashboard_components.py`:
+
+```python
+def test_tension_card_reading_panels_have_ai_badge():
+    """tension_card must add ✦ AI badge next to both reading labels."""
+    import streamlit as st
+    from unittest.mock import patch, call
+    from dashboard.components import tension_card
+
+    tension = {
+        "headline": "Revenue beat hides quality decline",
+        "weight": "material",
+        "bullish_reading": "Strong top-line momentum",
+        "bearish_reading": "One-time item inflated result",
+        "bullish_evidence": {"evidence_snippet": "q1", "reliability": "HIGH", "source": "10-Q"},
+        "bearish_evidence": {"evidence_snippet": "q2", "reliability": "HIGH", "source": "10-Q"},
+    }
+
+    with patch.object(st, "markdown") as mock_md:
+        tension_card(tension)
+        rendered = mock_md.call_args[0][0]
+
+    assert "✦ AI" in rendered
+    assert rendered.count("✦ AI") >= 2  # once per reading panel
+```
+
+- [ ] **Step 2: Run test to confirm it fails**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_tension_card_reading_panels_have_ai_badge -v
+```
+
+Expected: FAILED — "✦ AI" not in rendered HTML.
+
+- [ ] **Step 3: Modify `tension_card()` in `dashboard/components.py`**
+
+Find the `bull_side` variable inside `tension_card()`. Replace the single-div label line:
+
+```python
+# BEFORE — find this inside tension_card():
+f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+f'letter-spacing:0.09em;color:#059669;margin-bottom:6px;">Surface reading</div>'
+```
+
+Replace with:
+
+```python
+# AFTER
+f'<div style="display:flex;align-items:center;gap:5px;margin-bottom:6px;">'
+f'<span style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+f'letter-spacing:0.09em;color:#059669;">Surface reading</span>'
+f'{ai_badge("AI")}'
+f'</div>'
+```
+
+Then find the `bear_side` label inside `tension_card()`. Replace:
+
+```python
+# BEFORE — find this inside tension_card():
+f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+f'letter-spacing:0.09em;color:#dc2626;margin-bottom:6px;">Deeper reading</div>'
+```
+
+Replace with:
+
+```python
+# AFTER
+f'<div style="display:flex;align-items:center;gap:5px;margin-bottom:6px;">'
+f'<span style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+f'letter-spacing:0.09em;color:#dc2626;">Deeper reading</span>'
+f'{ai_badge("AI")}'
+f'</div>'
+```
+
+- [ ] **Step 4: Run test — expect pass**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_tension_card_reading_panels_have_ai_badge -v
+```
+
+Expected: PASSED
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dashboard/components.py tests/test_dashboard_components.py
+git commit -m "feat: mark tension card readings as AI interpretation"
+```
+
+---
+
+### Task 4: Update `quality_signal_chip()` — add AI label in expanded body
+
+**Files:**
+- Modify: `dashboard/components.py` (the `quality_signal_chip` function, lines ~191–234)
+
+The chip keeps its existing assessment color (positive/neutral/concerning). We add a small "✦ AI assessment" label above the rationale text in the expanded body only.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_dashboard_components.py`:
+
+```python
+def test_quality_signal_chip_body_has_ai_label():
+    """quality_signal_chip must include an AI label before the rationale text in the body."""
+    from dashboard.components import quality_signal_chip
+
+    signal = {
+        "dimension": "guidance_dynamics",
+        "assessment": "positive",
+        "rationale": "Management raised full-year guidance for the third consecutive quarter.",
+        "evidence": {"evidence_snippet": "raised guidance", "source": "10-Q", "reliability": "HIGH"},
+    }
+
+    html = quality_signal_chip(signal)
+    assert "✦ AI" in html
+    assert "Management raised full-year guidance" in html
+    # AI label must appear before the rationale text
+    assert html.index("✦ AI") < html.index("Management raised full-year guidance")
+```
+
+- [ ] **Step 2: Run test to confirm it fails**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_quality_signal_chip_body_has_ai_label -v
+```
+
+Expected: FAILED
+
+- [ ] **Step 3: Modify `quality_signal_chip()` in `dashboard/components.py`**
+
+Inside `quality_signal_chip()`, find the body div that contains the rationale:
+
+```python
+# BEFORE — find this in quality_signal_chip():
+f'<div style="font-size:0.78rem;color:{TEXT};line-height:1.5;">{rationale}</div>'
+```
+
+Replace with:
+
+```python
+# AFTER
+f'<div style="font-size:0.55rem;font-weight:600;text-transform:uppercase;'
+f'letter-spacing:0.07em;color:{AI_COLOR};margin-bottom:3px;">✦ AI assessment</div>'
+f'<div style="font-size:0.78rem;color:{TEXT};line-height:1.5;">{rationale}</div>'
+```
+
+- [ ] **Step 4: Run test — expect pass**
+
+```bash
+python -m pytest tests/test_dashboard_components.py::test_quality_signal_chip_body_has_ai_label -v
+```
+
+Expected: PASSED
+
+- [ ] **Step 5: Run the full test suite**
+
+```bash
+python -m pytest tests/test_dashboard_components.py -v
+```
+
+Expected: All 6 tests PASSED
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add dashboard/components.py tests/test_dashboard_components.py
+git commit -m "feat: mark earnings quality signal rationale as AI interpretation"
+```
+
+---
+
+### Task 5: Update `verdict.py` — `what_matters_most` and `non_obvious_takeaway`
+
+**Files:**
+- Modify: `dashboard/verdict.py`
+
+- [ ] **Step 1: Add `interpretation_card` to the import from `dashboard.components`**
+
+Find this line near the top of `dashboard/verdict.py`:
+
+```python
+from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card, tension_card, quality_signal_chip
+```
+
+Replace with:
+
+```python
+from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card, tension_card, quality_signal_chip, interpretation_card
+```
+
+- [ ] **Step 2: Replace the `what_matters_most` rendering block**
+
+Find and replace this block (around line 333):
+
+```python
+# BEFORE
+wmm = brief.get("what_matters_most", "")
+if wmm:
+    with st.expander("💡 What matters most", expanded=True):
+        st.markdown(
+            f"""
+            <div class="primer-card" style="background:{BG_MUTED};border:1px solid {BORDER};
+                        border-radius:12px;padding:20px 24px;margin-bottom:4px;">
+                <div style="font-size:0.62rem;font-weight:700;letter-spacing:0.1em;
+                            text-transform:uppercase;color:{TEXT_MUTED};margin-bottom:8px;">
+                    AI synthesis · the only interpretive field
+                </div>
+                <div style="font-size:1rem;line-height:1.7;color:{TEXT};">{wmm}</div>
+            </div>
+            """,
+            unsafe_allow_html=True,
+        )
+```
+
+Replace with:
+
+```python
+# AFTER
+wmm = brief.get("what_matters_most", "")
+if wmm:
+    with st.expander("💡 What matters most", expanded=True):
+        st.markdown(
+            interpretation_card(
+                "What matters most",
+                f'<div style="font-size:1rem;line-height:1.7;color:{TEXT};">{wmm}</div>',
+            ),
+            unsafe_allow_html=True,
+        )
+```
+
+- [ ] **Step 3: Replace the `non_obvious_takeaway` rendering block**
+
+Inside `_render_analytical_edge()`, find and replace (around line 246):
+
+```python
+# BEFORE
+if takeaway:
+    st.markdown(
+        f'<div class="primer-card" style="background:{BG_MUTED};border:1px solid {BORDER};'
+        f'border-left:4px solid {GREEN};border-radius:0 10px 10px 0;'
+        f'padding:16px 20px;margin-bottom:16px;">'
+        f'<div style="font-size:0.58rem;font-weight:700;text-transform:uppercase;'
+        f'letter-spacing:0.1em;color:{TEXT_MUTED};margin-bottom:6px;">Non-obvious takeaway</div>'
+        f'<div style="font-size:0.95rem;font-style:italic;line-height:1.65;color:{TEXT};">'
+        f'{takeaway}'
+        f'</div>'
+        f'</div>',
+        unsafe_allow_html=True,
+    )
+```
+
+Replace with:
+
+```python
+# AFTER
+if takeaway:
+    st.markdown(
+        interpretation_card(
+            "Non-obvious takeaway",
+            f'<div style="font-size:0.95rem;font-style:italic;line-height:1.65;color:{TEXT};">'
+            f'{takeaway}</div>',
+        ),
+        unsafe_allow_html=True,
+    )
+```
+
+- [ ] **Step 4: Verify no Python errors**
+
+```bash
+python -c "import dashboard.verdict"
+```
+
+Expected: no output (clean import).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dashboard/verdict.py
+git commit -m "feat: apply AI interpretation styling to what_matters_most and non_obvious_takeaway"
+```
+
+---
+
+### Task 6: Update `mda.py` — `language_shift`
+
+**Files:**
+- Modify: `dashboard/mda.py`
+
+- [ ] **Step 1: Add `interpretation_card` to the import in `mda.py`**
+
+Find this line near the top of `dashboard/mda.py`:
+
+```python
+from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card
+```
+
+Replace with:
+
+```python
+from dashboard.components import reliability_badge, source_badge, section_header, evidence_quote, fact_card, interpretation_card
+```
+
+- [ ] **Step 2: Remove `INFO`, `INFO_BG`, `INFO_BORDER` from the theme import if unused elsewhere**
+
+Check the theme import at the top of `dashboard/mda.py`:
+
+```python
+from dashboard.theme import (
+    GREEN, AMBER, RED,
+    BG, BG_MUTED, BORDER, TEXT, TEXT_MUTED, TEXT_FAINT,
+    INFO, INFO_BG, INFO_BORDER,
+)
+```
+
+After updating `language_shift`, `INFO_BG` and `INFO_BORDER` will no longer be used in this file. Remove them:
+
+```python
+from dashboard.theme import (
+    GREEN, AMBER, RED,
+    BG, BG_MUTED, BORDER, TEXT, TEXT_MUTED, TEXT_FAINT,
+)
+```
+
+(The `INFO` token is also unused — remove it too.)
+
+- [ ] **Step 3: Replace the `language_shift` rendering block**
+
+Find and replace (around line 52):
+
+```python
+# BEFORE
+if lang:
+    with st.expander("🔀 Language Shift vs Prior Periods", expanded=True):
+        st.markdown(
+            f"""
+            <div class="primer-card" style="background:{INFO_BG};border:1px solid {INFO_BORDER};
+                        border-radius:10px;padding:16px 18px;margin-bottom:16px;">
+                <div style="font-size:0.9rem;line-height:1.6;color:{TEXT};">{lang}</div>
+            </div>
+            """,
+            unsafe_allow_html=True,
+        )
+```
+
+Replace with:
+
+```python
+# AFTER
+if lang:
+    with st.expander("🔀 Language Shift vs Prior Periods", expanded=True):
+        st.markdown(
+            interpretation_card(
+                "Language shift",
+                f'<div style="font-size:0.9rem;line-height:1.6;color:{TEXT};">{lang}</div>',
+            ),
+            unsafe_allow_html=True,
+        )
+```
+
+- [ ] **Step 4: Verify no Python errors**
+
+```bash
+python -c "import dashboard.mda"
+```
+
+Expected: no output (clean import).
+
+- [ ] **Step 5: Run the full test suite**
+
+```bash
+python -m pytest tests/ -v --tb=short
+```
+
+Expected: all tests pass (no regressions).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add dashboard/mda.py
+git commit -m "feat: apply AI interpretation styling to language_shift in MD&A"
+```
+
+---
+
+## Post-Implementation Check
+
+After all 6 tasks are committed, do a visual check by running the app:
+
+```bash
+streamlit run app.py
+```
+
+Generate a brief for any ticker in your test data and verify:
+1. `what_matters_most` — purple left border + "✦ AI Synthesis" badge, not the old gray card
+2. `non_obvious_takeaway` (Analytical Edge section) — same purple treatment, no green border
+3. Tension cards — green/red backgrounds preserved, "✦ AI" badge appears next to both "Surface reading" and "Deeper reading" labels
+4. Earnings quality chips (expanded) — "✦ AI assessment" label appears above the rationale text
+5. MD&A Language Shift — purple treatment instead of blue
+6. All SourcedFact cards (what_changed, bull_points, bear_points) — unchanged