feat(bugs): support priority in list, show, and a new prioritize command

.claude/skills/detail-bugs/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: detail-bugs
-description: Interact with Detail bugs for a repository via the CLI — list and filter bugs, inspect reports, close as resolved or dismissed, and reopen previously closed bugs.
+description: Interact with Detail bugs for a repository via the CLI — list and filter bugs, inspect reports, close as resolved or dismissed, reopen previously closed bugs, and override a bug's priority.
 ---
 
 # Detail Bugs
 
-The Detail CLI exposes per-repository bugs through four subcommands: `list`, `show`, `close`, and `reopen`. This skill describes that surface so you can pick the right command for whatever the user is trying to do.
+The Detail CLI exposes per-repository bugs through five subcommands: `list`, `show`, `close`, `reopen`, and `prioritize`. This skill describes that surface so you can pick the right command for whatever the user is trying to do.
 
 ## Prerequisites
 
@@ -28,6 +28,8 @@ Lists bugs for the inferred or specified repository.
 
 - `--status pending|resolved|dismissed` — default `pending`; comma-separate or repeat the flag to combine (e.g. `--status resolved,dismissed`).
 - `--vulns` — only security vulnerabilities.
+- `--priority p1|p2|p3|none` — only bugs at these priorities; comma-separate or repeat the flag (e.g. `--priority p1,p2`). `none` selects bugs Detail never scored — most bugs found before priority scoring shipped, so prefer `--priority p1,p2,p3` over `--priority p1` when the user asks for "prioritized" bugs. Default: every priority.
+- `--sort newest|oldest|priority` — default `newest`. `priority` puts the most severe first and unscored last.
 - `--introduced-by <authors>` — filter by authors (comma-separated or repeated).
 - `--scan-id <wr_…>` — limit to a specific scan. Workflow IDs come from `detail scans list`.
 - `--since` / `--until` — accept a duration (`1d`, `24h`), an ISO date (`YYYY-MM-DD`), or an RFC3339 timestamp.
@@ -39,6 +41,8 @@ Lists bugs for the inferred or specified repository.
 
 Shows the full report for a single bug. Reports often include a suggested fix.
 
+Also shows `Priority` and, when Detail scored the bug, a `Rationale` explaining why. If someone has since overridden that score, an `Override` line reports what Detail originally assigned and why it was changed.
+
 - `--format table|json` — use `json` when parsing rather than displaying.
 
 ### `detail bugs close <BUG_ID>`
@@ -53,3 +57,13 @@ Marks a bug as resolved or dismissed. The CLI prompts for `--state` interactivel
 ### `detail bugs reopen <BUG_ID>`
 
 Flips a previously resolved or dismissed bug back to `pending`. Takes only the bug ID — useful when a fix is reverted or a dismissal is overturned.
+
+### `detail bugs prioritize <BUG_ID>`
+
+Overrides Detail's priority for a bug and records the change on its timeline. The CLI prompts for `--priority` interactively in a TTY; pass it explicitly when invoking non-interactively.
+
+- `--priority p1|p2|p3`.
+- `--comment "..."` — why the priority is changing. Worth passing: it is what a later `detail bugs show` reports as the override reason.
+- `--format table|json`.
+
+Setting the priority a bug already has is a no-op — the CLI reports "no change" rather than recording a second identical entry.

docs/HELP.md

@@ -14,6 +14,7 @@ This document contains the help content for the `detail` command-line program.
 * [`detail bugs show`↴](#detail-bugs-show)
 * [`detail bugs close`↴](#detail-bugs-close)
 * [`detail bugs reopen`↴](#detail-bugs-reopen)
+* [`detail bugs prioritize`↴](#detail-bugs-prioritize)
 * [`detail completions`↴](#detail-completions)
 * [`detail rules`↴](#detail-rules)
 * [`detail rules create`↴](#detail-rules-create)
@@ -115,6 +116,7 @@ List, show, and close bugs
 * `show` — Show the report for a bug
 * `close` — Close a bug as resolved or dismissed
 * `reopen` — Reopen a previously resolved or dismissed bug — flips it back to pending. Useful when a "fix" PR is reverted or a "won't fix" decision is overturned
+* `prioritize` — Set a bug's priority, overriding Detail's own assessment
 
 
 
@@ -137,6 +139,16 @@ List bugs for a given repository
   Possible values: `pending`, `resolved`, `dismissed`
 
 * `--vulns` — Only show security vulnerabilities
+* `--priority <PRIORITY>` — Only show bugs at these priorities — repeat the flag or comma-separate values (e.g. `--priority p1,p2`). Use `none` for bugs Detail never assigned a priority. Default: all priorities
+
+  Possible values: `p1`, `p2`, `p3`, `none`
+
+* `--sort <SORT>` — Result ordering. `priority` puts the most severe bugs first and unprioritized bugs last
+
+  Default value: `newest`
+
+  Possible values: `newest`, `oldest`, `priority`
+
 * `--introduced-by <INTRODUCED_BY>` — Only show bugs introduced by these authors (comma-separated or repeat flag)
 * `--scan-id <SCAN_ID>` — Filter bugs to a specific scan by workflow request ID
 * `--since <SINCE>` — Only show bugs created at or after this point. Accepts a duration (e.g. 1d, 24h, 30m) interpreted as "now minus this", an ISO date (YYYY-MM-DD), or an RFC3339 timestamp
@@ -220,6 +232,32 @@ Reopen a previously resolved or dismissed bug — flips it back to pending. Usef
 
 
 
+## `detail bugs prioritize`
+
+Set a bug's priority, overriding Detail's own assessment
+
+**Usage:** `detail bugs prioritize [OPTIONS] <BUG_ID>`
+
+###### **Arguments:**
+
+* `<BUG_ID>` — Bug ID
+
+###### **Options:**
+
+* `--priority <PRIORITY>` — Priority to set (prompted interactively if omitted in a TTY)
+
+  Possible values: `p1`, `p2`, `p3`
+
+* `--comment <COMMENT>` — Why the priority is changing — recorded on the bug's timeline
+* `--format <FORMAT>` — Output format
+
+  Default value: `table`
+
+  Possible values: `table`, `json`
+
+
+
+
 ## `detail completions`
 
 Print shell completion script to stdout.

openapi.json

@@ -72,6 +72,12 @@
             },
             "type": "array"
           },
+          "priority": {
+            "$ref": "#/components/schemas/Priority"
+          },
+          "priorityReason": {
+            "$ref": "#/components/schemas/PriorityReason"
+          },
           "repoId": {
             "$ref": "#/components/schemas/RepoId"
           },
@@ -180,6 +186,14 @@
         ],
         "type": "string"
       },
+      "BugSortOrder": {
+        "enum": [
+          "newest",
+          "oldest",
+          "priority"
+        ],
+        "type": "string"
+      },
       "BugSource": {
         "enum": [
           "review",
@@ -304,6 +318,37 @@
         "pattern": "^org_.*",
         "type": "string"
       },
+      "Priority": {
+        "description": "Detail's severity assessment, most severe first: P1 (High), P2 (Medium), P3 (Low).",
+        "enum": [
+          "P1",
+          "P2",
+          "P3"
+        ],
+        "type": "string"
+      },
+      "PriorityReason": {
+        "properties": {
+          "generatedPriority": {
+            "$ref": "#/components/schemas/Priority"
+          },
+          "isCurrent": {
+            "type": "boolean"
+          },
+          "overrideComment": {
+            "type": "string"
+          },
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "text",
+          "generatedPriority",
+          "isCurrent"
+        ],
+        "type": "object"
+      },
       "Repo": {
         "properties": {
           "fullName": {
@@ -570,6 +615,26 @@
               "$ref": "#/components/schemas/BugReviewState"
             }
           },
+          {
+            "description": "Comma-separated priorities to include, e.g. \"P1,P2\". Use \"none\" to include bugs that were never assigned a priority. Omit to include every priority.",
+            "example": "P1,none",
+            "in": "query",
+            "name": "priority",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "description": "Result ordering. `priority` puts the most severe bugs first and unprioritized bugs last.",
+            "in": "query",
+            "name": "sort",
+            "required": false,
+            "schema": {
+              "$ref": "#/components/schemas/BugSortOrder",
+              "default": "newest"
+            }
+          },
           {
             "in": "query",
             "name": "limit",
@@ -710,6 +775,95 @@
         "summary": "Get a bug"
       }
     },
+    "/public/v1/bugs/{bug_id}/priority": {
+      "post": {
+        "description": "Overrides Detail's priority for a bug and records the change on the bug's timeline. Setting the priority the bug already has is a no-op and returns no priorityChangeId.",
+        "operationId": "updatePublicBugPriority",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "bug_id",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/BugId"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "comment": {
+                    "description": "Why the priority is being changed.",
+                    "maxLength": 2000,
+                    "type": "string"
+                  },
+                  "priority": {
+                    "$ref": "#/components/schemas/Priority"
+                  }
+                },
+                "required": [
+                  "priority"
+                ],
+                "type": "object"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "priority": {
+                      "$ref": "#/components/schemas/Priority"
+                    },
+                    "priorityChangeId": {
+                      "pattern": "^bfrpc_.*",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "priority"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "OK"
+          },
+          "4XX": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            },
+            "description": "Client error"
+          },
+          "5XX": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            },
+            "description": "Server error"
+          }
+        },
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "summary": "Set a bug's priority"
+      }
+    },
     "/public/v1/bugs/{bug_id}/review": {
       "post": {
         "description": "Creates or updates a review on a bug (resolve, dismiss, or reopen).",