From 830fcc08038343e2ae1dc0a87abad88cff36917a Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Wed, 8 Jul 2026 00:08:14 -0700
Subject: [PATCH] fix(observability): clarify manual/commented/ignored panel
 semantics

The Manual review, Commented (advisory), and Ignored stat panels on
the maintainer Reviews & PRs dashboard count review_targets rows by
their most-recent status within the selected window, not lifetime
occurrences. A PR that entered manual review and was later resolved
in the same window disappears from these panels entirely, reading
lower than a maintainer's felt sense of activity. Add plain-language
panel descriptions explaining this latest-update-in-window semantics
and bump the dashboard version.

A true additive event-count metric sourced from audit_events is a
separate, larger follow-up (part 2 of #3717) pending investigation
of where review_targets.status is set to commented/ignored.

Advances #3717
---
 grafana/dashboards/maintainer-reviews.json   |  5 ++++-
 test/unit/selfhost-grafana-dashboard.test.ts | 17 +++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/grafana/dashboards/maintainer-reviews.json b/grafana/dashboards/maintainer-reviews.json
index 2fbdcbedbb..68bd54002b 100644
--- a/grafana/dashboards/maintainer-reviews.json
+++ b/grafana/dashboards/maintainer-reviews.json
@@ -4,7 +4,7 @@
   "tags": ["gittensory", "maintainer"],
   "timezone": "browser",
   "schemaVersion": 39,
-  "version": 4,
+  "version": 5,
   "editable": false,
   "graphTooltip": 1,
   "refresh": "1m",
@@ -54,6 +54,7 @@
       "type": "stat",
       "id": 5,
       "title": "Manual review",
+      "description": "Counts PRs whose most recent status update falls in this window AND is currently 'manual' -- a live snapshot, not a lifetime tally. A PR that entered manual review earlier in the window and was later merged or closed (also within the window) is counted only once, under Merged or Closed, not here. If you actively resolve your manual-review queue, this number will read lower than your felt sense of how many PRs passed through manual review.",
       "datasource": { "type": "frser-sqlite-datasource", "uid": "gittensory-db" },
       "gridPos": { "h": 4, "w": 4, "x": 12, "y": 1 },
       "fieldConfig": { "defaults": { "color": { "mode": "fixed", "fixedColor": "orange" }, "unit": "short" }, "overrides": [] },
@@ -64,6 +65,7 @@
       "type": "stat",
       "id": 6,
       "title": "Commented (advisory)",
+      "description": "Counts PRs whose most recent status update falls in this window AND is currently 'commented' -- the same in-window-latest-state semantics as 'Manual review'. A PR that was commented on and later merged or closed within the same window shows only under Merged/Closed, so this under-reports total advisory-comment activity for anyone who resolves their queue promptly.",
       "datasource": { "type": "frser-sqlite-datasource", "uid": "gittensory-db" },
       "gridPos": { "h": 4, "w": 4, "x": 16, "y": 1 },
       "fieldConfig": { "defaults": { "color": { "mode": "fixed", "fixedColor": "blue" }, "unit": "short" }, "overrides": [] },
@@ -74,6 +76,7 @@
       "type": "stat",
       "id": 7,
       "title": "Ignored",
+      "description": "Counts PRs whose most recent status update falls in this window AND is currently 'ignored' -- the same in-window-latest-state semantics as 'Manual review'. If a PR's status changes again later in the same window (e.g. re-triaged into manual/commented/merged/closed), it moves out of this count entirely rather than accumulating, so this does not track how many times a PR was ever ignored.",
       "datasource": { "type": "frser-sqlite-datasource", "uid": "gittensory-db" },
       "gridPos": { "h": 4, "w": 4, "x": 20, "y": 1 },
       "fieldConfig": { "defaults": { "color": { "mode": "fixed", "fixedColor": "purple" }, "unit": "short" }, "overrides": [] },
diff --git a/test/unit/selfhost-grafana-dashboard.test.ts b/test/unit/selfhost-grafana-dashboard.test.ts
index 0b6d216985..fe8f5099cf 100644
--- a/test/unit/selfhost-grafana-dashboard.test.ts
+++ b/test/unit/selfhost-grafana-dashboard.test.ts
@@ -16,6 +16,7 @@ type DashboardTarget = {
 type DashboardPanel = {
   id?: number;
   title?: string;
+  description?: string;
   targets?: DashboardTarget[];
 };
 
@@ -254,6 +255,22 @@ describe("maintainer Reviews & PRs Grafana dashboard", () => {
     }
   });
 
+  it("explains the latest-update-in-window (not lifetime) semantics on Manual/Commented/Ignored (#3717)", () => {
+    const dashboard = readDashboard();
+    const panelsById = new Map(dashboard.panels.map((panel) => [panel.id, panel]));
+
+    for (const [id, title] of [
+      [5, "Manual review"],
+      [6, "Commented (advisory)"],
+      [7, "Ignored"],
+    ] as const) {
+      const panel = panelsById.get(id);
+      expect(panel?.title).toBe(title);
+      expect(panel?.description?.length ?? 0).toBeGreaterThan(0);
+      expect(panel?.description).toContain("window");
+    }
+  });
+
   (sqliteCliAvailable ? it : it.skip)("filters the pull request table to the selected time window", () => {
     const root = tmpRoot();
     const db = join(root, "reporting.sqlite");