gh_issues

gh_issues — adaptive GitHub issues table

Render a repo's issues as one markdown table. The semantic columns (Type, Priority, Effort) are resolved through the repo's own scheme — its labels, native issue types, and project fields — discovered fresh on every run. Never impose a label convention on a repo; its vocabulary is the truth.

Strictly read-only. Never create, edit, close, comment on, or label anything. gh api graphql is used for read queries only — no mutations, ever.

Flags

Protocol

1. Preflight. Run gh auth status. If gh is missing or unauthenticated, stop with an actionable hint (install: https://cli.github.com · authenticate: gh auth login) — never render a partial table. Resolve the target repo: --repo owner/repo when given, otherwise the current directory's repo via gh repo view. Not inside a repo and no --repo → stop and ask for --repo owner/repo.
2. Flag validation. --limit must be numeric — reject with a usage line otherwise. An unknown --sort key → error listing the valid keys. Every user-supplied string (labels, search query, milestone, logins…) is passed to gh as a quoted argument — never interpolated unquoted, never through eval.
3. Scheme discovery. One gh label list --json name,description --limit 100 call. Classify the label families heuristically at runtime:
   • priority-ish — e.g. P1, prio/high, priority: high, critical
   • type-ish — e.g. bug, enhancement, type: feature, docs
   • effort-ish — e.g. size/M, effort: 3, XL, t-shirt sizes Nothing is hardcoded: classify whatever this repo actually uses, and derive each family's internal ranking from its own naming (P1 outranks P2; high outranks low; …).
4. Fetch. One gh issue list --json number,title,labels,assignees,milestone,body,state,updatedAt call, passing through every native filter flag the user gave (--state --label --assignee --author --milestone --search --limit); --mine expands to --assignee @me.
5. Relations & types (skipped entirely under --no-deps). One batched GraphQL query fetching, for the listed issues: the native issue-type name (when the repo/org has issue types) and parent/sub-issue ("tracked-by") relations; include the search's total issue count when the result may be truncated (footer, below). Combine relations with a body-marker scan — Depends on #N, Blocked by #N, Depends: #N, all case-insensitive. If the GraphQL query fails, degrade to body-marker-only detection and say so in a notice.
6. Semantic filtering. --type <t> and --priority <p> match through the discovered scheme — --priority high matches P1 in a P1/P2/P3 repo, with a mapping notice ("--priority high → P1"). A value not present in the scheme → error listing the values that DO exist. A scheme family absent entirely → one notice line and the flag is ignored.
7. Render per the rules below, including notices and the truncation footer.