# 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]