issue-triage

/issue-triage — classify, rank, and garden the open issue backlog

Lead with current first-class fak console issues, fak-dev issue, and fak dispatch surfaces. The Python triage helper remains a read-only legacy/debug fallback for report fields not yet exposed by those commands. Mutations stay a separate, operator-approved step.

A backlog rots the same way an index drifts: labels go missing, priorities never get set, questions hang open forever, duplicates accrete. This skill is the gardening pass for GitHub issues — the issue analogue of curate-cluster. One pass: gather → rank → propose → (approve) → apply → verify.

The triage ranking is a transparent integer score, not a model judgment (see the helper's module docstring for the exact formula). The score is surfaced in the report so the ordering is auditable.

Project contract

Reads .claude/project.yaml. Required keys:

• python — interpreter path (default: python).
• helpers.issue_triage — the read-only fetch/classify/rank/actions script.
• audits_dir — where reports + the actions manifest are written (default: docs/_audits/, shared with plan-audit — these are process residue, kept out of the root index scan).

If helpers.issue_triage is absent, print one line pointing at the missing helper and stop. Do not improvise a substitute.

The label taxonomy is the project's, baked into the helper (priority/P0|P1|P2, kind, area, workflow). Override thresholds or label sets via the helper's --config <json> if the taxonomy changes; the skill itself is taxonomy-agnostic.

Step 1 — Gather and rank (read-only)

fak console issues --state open --json > issues-ranked.json

# Legacy/debug comparison for extra historical report fields:
<p> <h.issue_triage> --markdown --out <audits_dir>/issue-triage-<YYYY-MM-DD>.md
<p> <h.issue_triage> --actions  --out <audits_dir>/issue-actions-<YYYY-MM-DD>.json

Use today's date in UTC. Use --out (not a shell > redirect) — PowerShell redirects re-encode to UTF-16 and mangle the · / — glyphs in the report. One report per day; overwrite if it exists.

Optional scoping:

• --since-days N — only issues touched in the last N days (use after a burst of filing, to triage just the new wave).
• --scope <tag> — filter the rows to one bucket: priority | kind | area | orphans | stale | dup | question. Drops the other sections so the report is focused.

Read the markdown report back (the helper prints wrote <path>, not the body). Do not page through gh issue list by hand — the helper already folded the whole open backlog into the ranked model.

Default medium-scale scout: OpenCode Go Ox Alpha

For a broad repository review or a medium-scale gardening batch (25 or more issues/candidates), use opencode-go/ox-alpha-free as a read-only proposal stage when that route is available. This is the default model-assisted path, not authority to mutate GitHub or the tree. If the route is unavailable, keep the deterministic report and continue without a model; do not silently substitute a paid model.

Run the scout with OpenCode's permission-constrained plan agent. Never pass --auto, and tell the model that shell commands are read-only too:

opencode run --agent plan --model opencode-go/ox-alpha-free --format json \
  "Read-only review. Inspect the ranked issue report and repository evidence. Do not edit files, create/comment/close issues, or run any mutating command. Return candidate findings only, each with: claim; exact witness command; observed output/count; affected paths or issue numbers; dedupe query and results; current parent issue state; proposed labels/milestone; confidence; and disconfirming evidence."

Save the session ID and the candidate packet beside the dated audit report. Treat model prose as an allegation until an independent pass reruns every witness. The measured rationale and failure examples are indexed in docs/notes/OX-ALPHA-DOGFOOD-2026-08-22.md.

Ox Alpha's audited failure mode is confident conflation: one true global smell can be combined with stale parent state, non-versioned residue, incomplete inventories, or incorrect attribution. Therefore the scout and gardener must not be the same self-certifying pass.

Step 2 — Read the report, lead with the load-bearing finding

The report's counts line is the headline. Lead the operator summary with the single largest gap, in this priority order:

1. Orphan P0/P1 (orphan count) — high-priority work with no claimant. This is the most expensive backlog rot. Name the top 3 by score.
2. needs-priority — the canonical "labels were never set" gap. A pass that cuts that number is a real win; quote the project's own current baseline from the report rather than a fixed number.
3. stale / dormant-question — these carry mechanical proposed actions (mark stale, close). They are the gardening moves the operator can approve in one batch.
4. duplicate clusters — run fak-dev issue dedup (the body-aware census; the triage helper no longer detects dups). Confirm-and-close candidates.

Before proposing dispatch for a selected issue, validate and price it through the first-class Go surfaces:

gh issue view N --repo owner/name --json number,title,body,labels > issue.json`nfak-dev issue contract --from-issues issue.json --json
fak dispatch issues --issues issue.json --json

Use tools/issue_contract.py or tools/issue_lane_router.py only to debug a discrepancy with those commands; do not teach them as the default operator path.

For every model-proposed candidate, the independent reconciliation pass must:

1. Rerun the exact witness command and preserve its output.
2. Check that the measurement actually supports the claim's scope and causal language (for example, filesystem residue outside go list ./... cannot explain a Go package build failure).
3. Read back every named parent/duplicate issue's current state.
4. Preserve the complete inventory behind any count; samples cannot support a “full list” acceptance condition.
5. Reject candidates that combine different leaves, non-versioned cleanup, or comment bookkeeping into one issue.
6. Materialize each survivor as a candidate JSON packet, then run:

fak-dev issue contract --file candidate.json --dedupe-checked \
  --strict-witness --strict-scale --strict-project-work \
  --strict-born-routed --strict-model-tier --json

A held verdict stays needs-triage / triage-only; it is not worker-ready. Create only passing candidates, with priority, generation, class, and milestone set at creation. After creation, read the issue back from GitHub and compare its title, body, labels, milestone, and parent against the accepted packet. A separate reconciliation pass may retain, rewrite, or close model-filed candidates; never use the filing trajectory's own summary as proof. Do not paste the whole report into chat — link the file. Surface only the 0–3 findings that matter and the one batch the operator can act on now.

Step 3 — Distinguish mechanical from judgment-call actions

The --actions JSON carries two kinds of entries:

• mechanical (cmd is set) — close-dormant-question and mark-stale. These are defensible from the issue's own signals (a question idle ≥ 30 d, or any non-P0/P1 idle ≥ 60 d). The operator can approve these as a batch.
• review-only (cmd: null, kind: "review") — needs-priority, needs-kind, needs-area, orphan. The helper cannot decide these algorithmically (what priority is the work?). They are surfaced for the operator to decide per-issue.

Never fabricate a cmd for a review-only action. If the operator sets a priority by hand, you build that single gh issue edit <n> --add-label priority/Px command on the spot — you do not promote the row to "mechanical".

Step 4 — Apply mechanical actions only on approval (dry-run first)

Before running anything, print the exact commands you will run, grouped by kind. The manifest's cmd strings are PowerShell-shell-ready (single-quoted --comment, double-quoted --reason); run them verbatim.

# Dry-run review — show, don't run. Confirm the counts match the manifest.
# Then, per batch, on explicit operator "yes":
gh issue close <n> --reason "not planned" --comment "..."   # dormant-question
gh issue edit <n> --add-label "stale" --add-comment '...'   # mark-stale

Rules:

• Batch by kind, and confirm each batch separately ("3 dormant-question closes — ok?"). Do not run a single blanket "apply everything".
• One issue at a time for any review-only action the operator resolves live. If they say "#98 is P0, already claimed" → gh issue edit 98 --add-label in-progress, nothing else.
• Re-fetch after applying — re-run Step 1's --actions and confirm the applied rows dropped out (their tags changed). The pass is done when the mechanical-action count is zero AND the operator has either resolved or explicitly deferred each review-only row.

Step 5 — Verify (witness, don't assume)

fak console issues --state open --json > issues-ranked-after.json
gh issue view <n> --json labels,state,comments   # spot-check 2–3 applied rows
<p> <h.issue_triage> --actions --out <audits_dir>/verify-actions.json

The first-class before/after issue models are the truth source; the fallback action manifest is an additional mutation witness when that helper was used.

The second run is the witness: the applied issues should no longer carry the tag the action addressed (a closed dormant-question is no longer open; a marked-stale issue now has the stale label). If a row's tag survived, the gh write failed silently — re-check and re-run that one.

The pass is done when: the report's mechanical-action count is zero, the operator has resolved or deferred every review-only row they chose to handle this pass, and the spot-checks confirm the GitHub state matches the manifest.

Running it on a cadence

This is a single pass. The backlog re-rots, so drive it with /loop (e.g. /loop issue-triage --since-days 30, weekly) — each pass only touches issues that aged into a bucket since the last one. The helper is idempotent: an issue already correctly labeled and claimed contributes nothing to the action manifest, and a pass with nothing to propose commits nothing and exits.

Where this misleads / honest limits

• The score is a heuristic, not a priority oracle. A P2 bug can matter more than a P1 enhancement; the formula can't see that. Treat the ranking as "where to look first", not "what to build first".
• Stale/dormant thresholds are calendar-based, not signal-based. A quiet issue that is actively blocked (waiting on a dependency) is not stale — the operator must read the close candidates before approving. The manifest's comment text says "reply to keep open" for exactly this reason.
• Duplicate detection lives in fak issue dedup, not this helper. The body-aware census (title + title+body simhash) catches semantic dups the old title-token Jaccard pass missed. It is advisory: it ranks merge proposals with per-pair evidence and suppresses oversized shared-template families (epic siblings are not duplicates of each other). Always confirm before closing as dup; it never writes to GitHub.
• It only sees labels + timestamps. It cannot read the issue body for severity, dependencies, or whether the reporter still cares. The operator's judgment is the last rung; this skill gets the queue into shape so that judgment is spent on the right rows.
• Closed issues are out of scope. This triages the open backlog. Auditing closed-issue quality (wrong reason codes, premature closes) is a different skill.