Git Issue Triage

Groom the open backlog. Read-only sweep -> bucketed report -> per-category confirm -> apply -> verify.

Report what the sweep returned, never what this file predicts. The buckets below define how to classify; the contents come from the run.

Flow

1. Sweep, read-only, two calls total:

   gh issue list --state open --limit 200 --json number,title,labels,assignees,createdAt,updatedAt,body
   gh label list --limit 200 --json name -q '.[].name'

   Why -> one batched fetch, never gh issue view per issue. A 60-issue backlog is 60 round trips that way, and the list payload carries every field the buckets need except the Stale comment count, fetched per Stale. Not comments - that field returns every comment body for every open issue, a context blowout on exactly the big backlogs this skill targets. 200 rows returned -> the cap was hit and the sweep is not authoritative; raise --limit or paginate before bucketing, and say so in the report

2. Zero open issues -> say so, stop. No report, no proposals

3. Corroborating fetch, only if step 1 produced Closeable candidates:

   gh search prs --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --merged --limit 100 --json number,title,body

   Grep those bodies for #<n>. Why -> a merged PR naming the issue is the only close signal that does not require reading the tree. 100 rows returned -> the cap was hit; raise --limit or paginate before treating the grep as evidence

4. Bucket every open issue into exactly one category. See Buckets
5. Report. One line per issue, grouped, counts in each heading. See Report Format
6. Confirm per category, never per issue and never all-at-once. AskUserQuestion, multiSelect, one option per non-empty actionable category. Why -> closing is irreversible in effect even though technically reopenable, relabelling is not, and the user is entitled to accept "labels yes, closes no"
7. Apply only the accepted categories, batched. See Apply
8. Summary: counts applied per category, plus one line per skipped issue with why. No recap of what step 5 already listed

Buckets

Exactly one bucket per issue. State buckets resolve before label buckets - Closeable > Likely duplicate > Blocked > Stale > Unlabeled > Unprioritized > Healthy. Why -> an issue about to be closed does not need a label argument first.

Unlabeled

No type: * label resolved through the chain below. Propose one derived from title + body text.

• Type picks and tiebreakers live in git-commit - read that table, do not re-derive one here
• Text carries no type signal at all -> propose nothing, list it as -> needs a human read

Unprioritized

Has a type, no priority: *. Propose a priority only where the text gives a real signal:

• Crash, data loss, security, production down -> critical or high
• Anything else -> propose nothing, and say so in the line

Why -> a guessed priority is worse than an absent one, it makes the backlog look sorted when it isn't.

Stale

updatedAt older than 90 days.

# BSD/macOS; GNU is `date -u -d '90 days ago' +%Y-%m-%dT%H:%M:%SZ`
date -u -v-90d +%Y-%m-%dT%H:%M:%SZ

Propose one of: ping, close as not planned, leave. Pick by the comment count, fetched for the Stale candidates only in a second targeted call - gh api repos/{owner}/{repo}/issues/<n> -q .comments returns the bare count, no bodies. A stale issue with real discussion gets ping, never close. Why -> people argued about it; closing silently discards that argument.

Likely Duplicate

Title or body overlaps another open issue. Propose linking + the duplicate label.

• Keep the older number as canonical, propose the label on the newer one
• Propose the link, the label, and closing the newer via gh issue close <newer> --duplicate-of <older> in this category's confirm. Why -> --duplicate-of records the duplicate relation and the duplicate state reason; closing as completed or not planned misstates why it closed

Closeable

The work appears done, evidenced by one of:

• A merged PR from step 3 references #<n>
• The described defect no longer reproduces in the current tree, verified by actually looking

Propose close with state_reason: completed. No evidence -> it is not Closeable, it is Stale.

Blocked

Body or comments name an unmet dependency. Propose the blocked label + a comment naming the blocker. Comment obeys Comment Length below.

Healthy

Fully labelled (type: * present, recently touched). Count only, do not list. Why -> a report that lists everything is a report nobody reads.

Label Resolution

Never hardcode the namespaced taxonomy. Detect it with the gh label list from Flow step 1, then resolve each intended label through its candidate chain, first existing name wins:

• Whole chain missing -> drop that label and say so in the output. Never gh label create
• Exactly one type: * label per issue. Pick the dominant type, never two
• priority: * only when the text signalled urgency. Never guess a priority
• Multi-word label names must be quoted: --label "type: bug"

Report Format

Grouped by bucket, count in the heading, one line per issue, no prose between groups -> references/report-format.md.

Titles truncate at 50 chars. Lead with: "N open, N actionable across M categories."

Apply

Batched per category, after that category was accepted. gh issue edit takes many numbers in one call:

gh issue edit 42 58 --add-label "type: bug"
gh issue edit 42 --add-label "priority: high"
gh issue close 34 --reason completed --comment "Landed in #77"
gh issue close 17 --reason "not planned"
gh issue close 61 --duplicate-of 42
gh issue comment 48 --body "Blocked on #34 - the loader lands there first."

• Every close passes an explicit --reason completed, --reason "not planned", or --duplicate-of <n>. Why -> without it GitHub records completed, so every abandoned spike reads in the timeline as shipped work
• Edit fails -> surface it, keep going with the rest of the batch, list it as skipped in step 8. No blind retry
• Comment bodies obey Comment Length - 4 lines, facts only

Comment Length

Triage writes no issue bodies, only comments. Hard cap: 4 lines of prose per comment.

• State the fact and stop: what blocks it, which issue duplicates it, what evidence closed it
• One line each, 100 chars or fewer. No sub-bullets
• Link rather than summarize: blocked by #38 beats a paragraph about #38

Prohibitions:

• State the fact, not the process. No "I reviewed this and determined that"
• No restating the issue title. The reader is looking at it
• Never invent a blocker, duplicate, or merged PR you did not verify
• No "just checking in on this", no apologizing for the triage pass

Good:

Blocked by #38 - the label taxonomy has to land before this can resolve chains.

Bad - restates the title, narrates the triage, invents a timeline:

I reviewed this issue as part of a backlog pass. The label chain problem
described in the title is still outstanding. We will need the taxonomy work
completed first. We should be able to revisit this in the next sprint.

Delegation

• New standalone issue -> git-issue-create
• Picking a triaged issue up and branching -> git-issue-start
• A triaged issue too big to be one task -> say so in the report and let the user split it; never split it yourself
• Local branch clutter, the same sweep shape one layer down -> git-branch-cleanup

Rules

• Sweep is read-only. Nothing changes before a per-category confirm
• Never close an issue whose category the user did not accept. Partial acceptance is the normal outcome, not an edge case
• Never gh label create. Chain missing -> drop the label, name it in the report
• Never guess a priority. No urgency signal in the text -> no priority: *
• Never edit issue titles or bodies. Labels, assignees, state, and comments only. Why -> retitling other people's issues loses their words, and the tracker's value is that it records what they wrote
• Assignees change only on explicit ask. Unassigning someone is not grooming
• Never gh issue view in a loop. One batched list, per Flow step 1; the sole per-issue fetch is the Stale candidates' comment count, per Stale
• Closeable needs evidence - a merged PR or a verified non-repro. "Probably fixed" is Stale
• Healthy issues are counted, never listed
• Empty backlog -> say so and stop. Don't manufacture categories