stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
9a4cd2e0f78b9a3bec971fdb14da709fe6fcec1d
git.stella-ops.org/docs/product-advisories/26-Dec-2025 - AI Surfacing UX Patterns.md
StellaOps Bot 907783f625 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.
2025-12-26 15:17:58 +02:00

4.3 KiB
Raw Blame History

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]