(docs) Document issues command

Signed-off-by: Arisu Tachibana <[email protected]>

Author: aliceinwire

docs/issues.md

@@ -0,0 +1,161 @@
+# `kci-dev issues detect` — KCIDB Issue Fetcher
+
+Fetch KernelCI Database (KCIDB) issues associated with **builds** and **boots**, and detect **new issues** (first‑time observations) for a specific checkout.
+
+---
+
+## Synopsis
+
+```bash
+kci-dev issues detect [--builds | --boots | --new]
+                     [--id <build-or-boot-id>]
+                     [--all-checkouts]
+                     [--days <N>] [--arch <ARCH>] [--origin <ORIGIN>] [--latest]
+                     [--giturl <URL> --branch <BRANCH> --commit <COMMIT>]
+                     [--git-folder <PATH>]
+```
+
+> Use one operating mode at a time: `--builds`, `--boots`, or `--new`.
+
+---
+
+## Description
+
+* **Build/boot issue fetch**: Retrieve KCIDB issues linked to a specific build/boot (`--id`) or across *all available trees* on the dashboard (`--all-checkouts`).
+* **New‑issue detection**: Identify issues **observed for the first time** for a checkout (defined by `--giturl/--branch/--commit`, or discovered via `--git-folder`).
+* **Scope control**: Restrict queries by architecture, time window, result recency, and data origin. Default origin is `maestro`.
+
+`--all-checkouts` targets **failed** and **inconclusive** builds/boots across the dashboard, limited by the `--days` window.
+
+---
+
+## Common Workflows
+
+### Detect build issues for a specific build ID
+
+```bash
+kci-dev issues detect --builds --id <build-id>
+```
+
+### Detect build issues across all checkouts (recent window)
+
+```bash
+kci-dev issues detect --builds --all-checkouts --days 7 --origin maestro
+```
+
+### Detect boot issues for a specific boot ID
+
+```bash
+kci-dev issues detect --boots --id <boot-id>
+```
+
+### Detect boot issues across all checkouts (recent window)
+
+```bash
+kci-dev issues detect --boots --all-checkouts --days 14 --origin maestro
+```
+
+### Detect **new** issues for a checkout (dashboard scan)
+
+```bash
+kci-dev issues detect --new --all-checkouts --days 7 --origin maestro
+```
+
+### Detect **new** issues for an explicit checkout (git tuple)
+
+```bash
+kci-dev issues detect --new \
+  --giturl https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git \
+  --branch main \
+  --commit v6.12 \
+  --origin maestro
+```
+
+### Filter to a specific architecture and pick the latest available results
+
+```bash
+kci-dev issues detect --builds --all-checkouts --arch arm64 --days 3 --latest
+```
+
+> The examples above mirror the CLI help and show the intended combinations.
+
+---
+
+## Options
+
+### Mode & Targets
+
+* `--builds`
+  Fetch KCIDB issues for **builds**.
+* `--boots`
+  Fetch KCIDB issues for **boots**.
+* `--new`
+  Detect **new** KCIDB issues (first‑time observations) for a checkout.
+* `--id <build-or-boot-id>`
+  Retrieve issues for a **single** build/boot. Use with `--builds` or `--boots`.
+
+### Dashboard Scope
+
+* `--all-checkouts`
+  Fetch issues for **all failed/inconclusive** builds/boots across **all available trees** on the dashboard (bounded by `--days`).
+* `--days <N>` *(int, default: 7)*
+  Time window (in days) to consider when scanning dashboard results.
+* `--origin <ORIGIN>` *(default: `maestro`)*
+  KCIDB origin to query.
+* `--arch <ARCH>`
+  Filter results by architecture (e.g., `arm64`, `x86_64`).
+* `--latest`
+  Select the **latest** results available within the query.
+
+### Checkout Specification (for `--new`)
+
+Provide the checkout explicitly **or** let the tool infer it from a local repo.
+
+* `--giturl <URL>`
+  Git URL of the kernel tree.
+* `--branch <BRANCH>`
+  Branch to evaluate.
+* `--commit <COMMIT>`
+  Commit SHA or tag (e.g., `v6.12`).
+* `--git-folder <PATH>`
+  Path to a local **git repository**. Must exist and be a directory. When provided, the tool may derive `giturl/branch/commit` from the local checkout.
+
+---
+
+## Behavior Notes
+
+* **Choose a mode**: Use one of `--builds`, `--boots`, or `--new` depending on your task.
+* **Single item vs. dashboard scan**:
+
+  * Use `--id` for a single build/boot.
+  * Use `--all-checkouts` (optionally with `--arch`, `--days`, `--latest`) to sweep across dashboards.
+* **New‑issue detection** focuses on first occurrences relative to a checkout tuple (`giturl`, `branch`, `commit`). If only `--git-folder` is given, the tool attempts to infer the tuple.
+* **Defaults**: `--origin maestro`, `--days 7`.
+
+---
+
+## Examples (from CLI help)
+
+```bash
+# Detect build issues
+kci-dev issues detect --builds --id <build-id>
+kci-dev issues detect --builds --all-checkouts --days <number-of-days> --origin <origin>
+
+# Detect boot issues
+kci-dev issues detect --boots --id <boot-id>
+kci-dev issues detect --boots --all-checkouts --days <number-of-days> --origin <origin>
+
+# Detect new issues for a checkout
+kci-dev issues detect --new --all-checkouts --days <number-of-days> --origin <origin>
+kci-dev issues detect --new --giturl <git-url> --branch <git-branch> --commit <commit> --origin <origin>
+```
+
+---
+
+## Troubleshooting
+
+* **No results**: Check your `--days` window, `--origin`, and that the target builds/boots are *failed* or *inconclusive* when using `--all-checkouts`.
+* **Checkout not resolved**: When using `--new`, ensure the `--giturl/--branch/--commit` tuple is provided, or pass `--git-folder` that points to a valid git repo.
+* **Architecture filter too narrow**: Try removing `--arch` or broadening it.
+
+---