git.stella-ops.org/docs/product-advisories/25-Dec-2025 - Visual Diffs for Explainable Triage.md

Here’s a simple, high‑leverage UX pattern you can borrow from top observability tools: treat every policy decision or reachability change as a visual diff.

---

Why this helps

• Turns opaque “why is this verdict different?” moments into quick, explainable triage.
• Reduces back‑and‑forth between Security, Dev, and Audit—everyone sees the same before/after evidence.

Core UI concept

• Side‑by‑side panes: Before (previous scan/policy) vs After (current).
• Graph focus: show the dependency/reachability subgraph; highlight added/removed/changed nodes/edges.
• Evidence strip (right rail): human‑readable facts used by the engine (e.g., feature flag OFF, code path unreachable, kernel eBPF trace absent).
• Diff verdict header: “Risk ↓ from Medium → Low (policy v1.8 → v1.9)”.
• Filter chips: Scope by component, package, CVE, policy rule, environment.

Minimal data model (so UI is easy)

• GraphSnapshot: nodes, edges, metadata (component, version, tags).
• PolicySnapshot: version, rules hash, inputs (flags, env, VEX sources).
• Delta: added/removed/changed for nodes, edges, and rule outcomes.
• EvidenceItems[]: typed facts (trace hits, SBOM lines, VEX claims, config values) with source + timestamp.
• SignedDeltaVerdict: final status + signatures (who/what produced it).

Micro‑interactions that matter

• Hover a changed node ⇒ inline badge explaining why it changed (e.g., “now gated by --no-xml runtime flag”).
• Click a rule change in the right rail ⇒ spotlight the exact subgraph it affected.
• Toggle “explain like I’m new” ⇒ expands jargon into plain language.
• One‑click “copy audit bundle” ⇒ exports the delta + evidence as an attachment.

Where this belongs in your product

• Primary: in the Triage view for any new finding/regression.
• Secondary: in Policy history (compare vX vs vY) and Release gates (compare build A vs build B).
• Inline surfaces: small “diff pills” next to every verdict in tables; click opens the big side‑by‑side.

Quick build checklist (dev & PM)

• Compute a stable graph hash per scan; store snapshots.
• Add a delta builder that outputs added/removed/changed at node/edge + rule outcome levels.
• Normalize evidence items (source, digest, excerpt) so the UI can render consistent cards.
• Ship a Signed Delta Verdict (OCI‑attached) so audits can replay the view from the artifact alone.
• Include hotkeys: 1 focus changes only, 2 show full graph, E expand evidence, A export audit.

Empty state & failure modes

• If evidence is incomplete: show a yellow “Unknowns present” ribbon with a count and a button to collect missing traces.
• If graphs are huge: default to “changed neighborhood only” with a mini‑map to pan.

Success metric (simple)

• Mean time to explain (MTTE): time from “why did this change?” to user clicking “Understood”. Track trend ↓.

If you want, I can sketch a quick wireframe (header, graph panes, evidence rail, and the export action) or generate a JSON schema for the Delta and EvidenceItem objects you can hand to your frontend.