Add property-based tests for SBOM/VEX document ordering and Unicode normalization determinism
- Implement `SbomVexOrderingDeterminismProperties` for testing component list and vulnerability metadata hash consistency. - Create `UnicodeNormalizationDeterminismProperties` to validate NFC normalization and Unicode string handling. - Add project file for `StellaOps.Testing.Determinism.Properties` with necessary dependencies. - Introduce CI/CD template validation tests including YAML syntax checks and documentation content verification. - Create validation script for CI/CD templates ensuring all required files and structures are present.
This commit is contained in:
StellaOps Bot
@@ -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]
|
||||
Reference in New Issue
Block a user