fixes save

docs/product-advisories/archived/26-Dec-2025 - AI Surfacing UX Patterns.md

@@ -0,0 +1,117 @@
+# AI Surfacing UX Patterns Advisory
+
+**Status:** ANALYZED - Sprint Created
+**Date:** 2025-12-26
+**Type:** UX/Design Advisory
+**Implementation Sprint:** SPRINT_20251226_020_FE_ai_ux_patterns
+
+---
+
+## Executive Summary
+
+This advisory defines how AI results should surface in Stella Ops without becoming obtrusive. The core principle: **AI must behave like a high-quality staff officer—present when needed, silent when not, and always subordinate to evidence and policy.**
+
+## Core Design Principles
+
+### 1. Deterministic Verdict First, AI Second
+
+**Non-negotiable UI ordering:**
+1. Deterministic verdict (authoritative): severity, policy state, exploitability, SLA, delta
+2. Evidence summary (authoritative): minimal proof set that drove the verdict
+3. AI assist (non-authoritative unless evidence-backed): explanation, remediation, suggestions
+
+### 2. Progressive Disclosure UX
+
+AI should not add new screens or workflows. It appears as small, optional expansions:
+- **AI Chips**: Short (3-5 words), action-oriented, clickable
+- **"Explain" drawer**: Opens on click, not by default
+
+Chip examples:
+- "Likely Not Exploitable"
+- "Reachable Path Found"
+- "Fix Available: 1-step"
+- "Needs Evidence: runtime"
+- "VEX candidate"
+
+### 3. The "3-Line Doctrine"
+
+AI output constrained to 3 lines by default:
+- Line 1: What changed / why you're seeing this now
+- Line 2: Why it matters in this service
+- Line 3: Next best action (single step)
+
+Everything else behind "Show details" / "Show evidence" / "Show alternative fixes"
+
+### 4. Surface-by-Surface Guidance
+
+| Surface | AI Behavior |
+|---------|-------------|
+| Findings list | 1-2 AI chips max per row; no paragraphs in list view |
+| Finding detail | 3-panel layout: Verdict → Evidence → AI (subordinate) |
+| CI/CD output | Opt-in only (`--ai-summary`); max 1 paragraph |
+| PR comments | Only on state change + actionable fix; no repeated comments |
+| Notifications | Only on state changes; never "still the same" |
+| Executive dashboards | No generative narrative; "Top 3 drivers" with evidence links |
+
+### 5. Contextual Command Bar ("Ask Stella")
+
+Not a persistent chatbot; a scoped command bar:
+- Auto-scoped to current context (finding/build/service/release)
+- Suggested prompts as buttons: "Explain why exploitable", "How to fix?"
+- Freeform input as secondary option
+
+### 6. Clear Authority Labels
+
+Every AI output labeled:
+- **Evidence-backed**: Links to evidence nodes, citations valid
+- **Suggestion**: No evidence; user decision required
+
+### 7. User Controls
+
+- AI verbosity: Minimal / Standard / Detailed
+- AI surfaces: Toggle per surface (PR comments, CI logs, UI)
+- Notifications: Default off; per-team opt-in
+
+## Implementation Status
+
+### Created Sprint
+
+**SPRINT_20251226_020_FE_ai_ux_patterns** (44 tasks):
+- Phase 1: Core AI Chip Components (7 tasks)
+- Phase 2: 3-Line AI Summary Component (5 tasks)
+- Phase 3: AI Panel in Finding Detail (6 tasks)
+- Phase 4: Contextual Command Bar (6 tasks)
+- Phase 5: Findings List AI Integration (5 tasks)
+- Phase 6: User Controls & Preferences (5 tasks)
+- Phase 7: Dashboard AI Integration (4 tasks)
+- Phase 8: Testing & Documentation (6 tasks)
+
+### Dependency Updates
+
+This sprint is a dependency for:
+- **SPRINT_20251226_015_AI_zastava_companion**: ZASTAVA-15/16/17/18 (FE tasks)
+- **SPRINT_20251226_013_FE_triage_canvas**: TRIAGE-14/15/16/17 (AI panel tasks)
+- **SPRINT_20251226_016_AI_remedy_autopilot**: REMEDY-22/23/24 (FE tasks)
+
+### Existing Components to Extend
+
+| Component | Pattern Alignment | Extension Needed |
+|-----------|-------------------|------------------|
+| `ReachabilityChipComponent` | ✓ Compact chip | None |
+| `VexStatusChipComponent` | ✓ Compact chip | None |
+| `EvidenceDrawerComponent` | ✓ Progressive disclosure | Add AI tab |
+| `FindingsListComponent` | Partial | Add AI chip slots |
+| `ConfidenceTierBadgeComponent` | ✓ Authority indicator | Extend for AI |
+
+## Key Constraints
+
+1. **No AI text on list views** - chips only
+2. **3-line default AI** - expandable for more
+3. **No AI in CI logs unless opt-in** - `--ai-summary` flag
+4. **PR comments only on state change + actionable fix**
+5. **AI always subordinate to evidence + deterministic policy**
+6. **AI must never auto-change enforcement** - no silent downgrades, waivers, or overrides
+
+## Advisory Content
+
+[Full advisory content preserved in sprint documentation]