Add Christmass advisories

docs/product-advisories/25-Dec-2025 - Visual Diffs for Explainable Triage.md

@@ -0,0 +1,56 @@
+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.