fr-triage

fr-triage

Announce: "I'm using fr-triage to triage ." You rank issues; fr triage keeps your ranking in a file.

Pages and state

Four pages, one question each: the backlog page triage.html (fr triage render: what do I do next?), origins (fr triage origins render), architecture (fr triage architecture render) and history (fr triage history render: how did we get here?). Hand-written analysis lives in fragments listed in <state>/<page>/manifest.yaml, never in an edited page; the dirs are board/ (for triage.html, not the Kanban board.html), origins/, architecture/ and history/. fr triage state export --to <dir> / import --from <dir> copy the durable state to and from a repo; export: {path: <dir>} in .fr/triage.yaml makes batch drive export finished waves (see The driver).

Everything lives in $HOME/.cache/fr/triage/<scope>/ (owner--repo for --repo OWNER/REPO, owner for --org OWNER, lowercased). --repo A/B,C/D is a group; two repos with same name are refused (keys are <repo-name>#<n>); batches stay single-repo.

Stages are derived by check and render, never stored. Never write facts yourself.

The loop (a re-run of it is the sync)

1. Collect. fr triage collect --repo OWNER/REPO (or --org OWNER). If the PR list hit its limit, re-run once with --pr-limit 1000, then go on and report it; for an issue- or repo-list warning, say rows may be missing.
2. Check. fr triage check --repo OWNER/REPO [--json] prints these sets and always exits 0:
   • unranked / unranked PRs: open, with no judgement. Your work queue (PRs: see below).
   • settled: judged, now closed or merged. Report what shipped; keep the judgement.
   • orphaned: the key names no repo collect read (a typo'd or renamed repo). Fix the key, or remove it if the repo is gone. This is the only set you may act on without the forge.
   • unreachable: collect could not settle it; the reason is printed. Transient (rate limit, 5xx, lost access): never prune on it. "Judged after the last collect" means collect again; not-found is a deleted issue or typo'd number: confirm on the forge (on GitHub, gh issue view), then fix the number or recommend removing it.
   • stale dispatch: a batch dispatch with no PR after stale_dispatch_days. Report it.
   • awaiting live: open issues carrying fr:awaiting-live (a merged PR only Refs'd them: a post-merge walk is still owed). Their own set (awaiting_live in --json), never ranked, proposed, unranked or unplaced; the board shows them in a group of their own, and a batch whose open members ALL await live is held (no Next up row, holds no wave open). The operator closes one once the walk is recorded (fr acceptance set-status --walk prints the command).
   • unplaced: open, in no open batch, no features group and not kind: parked (a cancelled batch's members count). Place each: a batch, a feature group, or park it; a judged duplicate is never listed. no severity: open and judged, no severity; set one. duplicate target unknown / duplicate chained: a duplicate_of the forge would not show, or one naming another duplicate; fix the key.
   • duplicate candidates: groups of open issues the engine proposes as duplicates, each pair with its reasons (close titles, shared rare identifiers, a shared finding id and issue reference, same theme). A proposal, not a verdict: judge every group (step 3). duplicates: each open issue judged duplicate_of, with its original's state (open, closed, missing) and, unless missing, the exact close command (on GitHub, gh issue close N --repo OWNER/REPO --duplicate-of <url>): report it to the operator, never run it.
3. Judge the unranked. Read each from facts.json (bodies stop at 2,000 characters; read the issue on the forge when cut off: on GitHub, gh issue view) and the code; a first run creates the file with schema: 3 and tiers. Compare against ALL judgements. Then judge each duplicate candidate group: re-read its issues, and set duplicate_of: <original> on each duplicate (the original is the issue with the fuller evidence, else the older one), or distinct_from: [<other>] when they differ, so the pair is not proposed again.
4. Render. fr triage render --repo OWNER/REPO --open writes triage.html and a snapshot. The board reads: Since last report (the diff from the previous snapshot), Needs you now (computed, never typed: green drafts, failing CI, blocked batches, stale dispatches, unfinished post_merge, unplaced issues), Next up (the driver's own order), Waves (tabs, closing order, features, parked), then the backlog by tier. Report back the board's path, what changed, what needs the operator and the forge commands you recommend (on GitHub, gh …).
5. Batch. Propose groups of judged issues to ship as one run and one PR (fr triage batch suggest is input, never the answer); create the accepted ones with fr triage batch create <id> --title T --issue KEY....