triage-issues

name

triage-issues

description

Review and assess every issue in the TMDb project board's Backlog column — re-verify each against current main with a read-only fan-out, close the mechanically dead, promote the actionable to Ready with priority, size and execution order, and leave the rest in Backlog naming the decision they need. Use to groom the backlog, before planning a release, or on a schedule. Runs headless: it decides for itself within the rules below.

Triage Issues

Grooms the Backlog column of the TMDb GitHub Project into a queue someone can work from without asking a question first.

The board is at github.com/users/adamayoung/projects/<n>; issues live in adamayoung/TMDb. This skill owns the Ready test, the four exits, the wontfix rules and the skip rule; the priority and size rubrics live in .claude/workflows/triage-issues.js (RUBRIC), the copy handed to every agent — nothing else in the repo restates any of them. Issue creation is owned by .github/ISSUE_FILING.md; this skill consumes what that produces.

Contract

Input: nothing. It discovers its own work. Output: field updates on the board, at most one comment per changed issue, a Project status update carrying the ordered run-list, and a summary to the caller. Never: opens a PR, edits source, or changes an issue that is not in Backlog.

Phase 1 — Resolve the board, and the tree

Project operations go through the GitHub MCP (mcp__github__projects_*), not gh project. Per ADR-0009 the MCP is the default and gh covers only the enumerated exceptions, which Projects is not — and concretely, gh project requires a read:project token scope this repo's usual token does not carry, so the gh route fails at the first call.

Resolve by title, never a hard-coded number — the number changes if the board is recreated, and a stale number makes every later write a silent no-op:

mcp__github__projects_list / list_projects   owner: adamayoung, owner_type: user
→ select the project whose title is exactly "TMDb"

Zero matches or more than one → stop and say so. Do not guess.

"Headless" here means unattended within a session — it decides for itself. It cannot run on a GitHub Actions runner: the Project MCP is user-scoped and is not mounted there (ADR-0009 records this as the reason claude.yml and integration-failure.yml stay on git/gh), and gh project needs a scope this repo's token lacks. Wiring this to a cron would fail at the call above.

Then pin the tree the verdicts are about. The Ready test says "re-verified at HEAD", which is worth nothing if HEAD is a stale checkout or a feature branch — run this skill from an unfetched branch and every verdict is stamped against history while claiming to be current.

git fetch origin
git rev-parse --abbrev-ref HEAD    # must be main
git rev-parse --short origin/main  # this is the sha passed to the workflow

Not on main, or main behind origin/main → say so and stop. The agents run git log in this checkout, so the checkout has to be the thing being triaged.

A skill cannot be tested from the branch that introduces it. This guard demands main, and checking out main removes an unmerged skill file — so the first real run necessarily comes after the merge. That is the right way round: a branch's tree is not what the issues are about. When this was first hit, Sources/ and Tests/ were identical to main but ci.yml, Makefile and Scripts/ were not — which is exactly what two of the open CI issues were about. Dry-run the workflow directly if you need to exercise the machinery before merging; do not relax this.

Capture that sha and today's date; both are passed to the workflow, which cannot compute a date itself.

Phase 2 — Adopt orphans

Any open issue in adamayoung/TMDb that is not on the board is invisible to this skill. Sweep them in before triaging, or a forgotten project assignment silently loses work:

gh issue list --repo adamayoung/TMDb --state open --limit 200 --json number,url

Add each missing one with projects_write / add_project_item, then set its Status to Backlog explicitly with update_project_item. Do not rely on the board's "Item added" workflow to do it: whether that automation is enabled is not queryable through the API and nothing here can check it. If it is off, adopted items arrive with no Status — and since Phase 3 onward works from the Backlog set and the scope rule forbids touching anything outside Backlog, they would be permanently invisible. That is the precise outcome this phase exists to prevent, so it must not depend on an unverifiable assumption.

For the same reason, Phase 3 treats an item with empty Status as Backlog.

Report the count adopted. A growing count usually means an issue-filing skill is skipping its board step — a bug in that skill, not here. One standing exception: .github/workflows/integration-failure.yml files its alert issue with plain gh issue create and cannot add it to the board, for the same reason this skill cannot run on a runner. Those arrive as orphans every time. Adopt them, but do not read them as a filing bug — and take care triaging one that tracks an in-flight fix PR, since it is not stale, it is in progress.

Phase 3 — Skip what cannot have changed

Do this before fanning out, not after. A triage agent costs roughly 80k tokens, so a full backlog is over a million tokens a run. The comment-suppression rule in Phase 7 saves noise; it does not save any of that, because the agent has already run by the time the digest is compared. On a schedule, most runs would spend a million tokens re-discovering that nothing moved.

For each Backlog issue, read the most recent triage marker in its comments:

<!-- triaged: <sha> | <digest> | <exit> | <priority> | <size> | deps=<csv> -->

Skip the agent when all four hold:

1. the marker's <sha> matches the origin/main sha from Phase 1 — compare by prefix, either direction, since one may be short and the other full;
2. the issue's updated_at is no later than the marker comment's updated_at — that is the operational test, and it is why Phase 7 writes the marker comment last: any label or field write landing after it would stamp the issue as touched by this skill's own hand, and the item would re-triage forever;
3. the marker is less than 30 days old; and
4. the previous verdict's verifiedBy cites no live-API check, and its priority rests on no dated trigger (see below).

A skipped issue carries its marker's exit, priority, size and deps forward, which is why the marker holds them rather than the digest alone — it keeps its place in the ordering without an agent having read it.

Conditions 3 and 4 exist because "main has not moved" is narrower than it sounds. A verdict rests on three things this repo does not control:

• The live TMDb API. Agents are told to re-check API claims with mcp__tmdb__* rather than trust the body. The API drifts on its own schedule; an issue can start or stop reproducing with main untouched.
• The calendar. P1 means "a latent break with a scheduled trigger". That trigger can fire between runs, turning a P1 into a P0 while nothing in the repo changed.
• Dependencies closed elsewhere. An issue blocked on another can become unblocked by that one being closed — including closed as wontfix, which is no commit at all.

The 30-day ceiling costs one full sweep a month and bounds all three.

Anything else is triaged: no marker, an unparseable one, a moved main, a touched issue, an old marker, or a live-API/dated-trigger verdict. Prefer re-triaging on doubt — the cost of a needless agent is tokens, the cost of a wrongly-skipped one is a stale verdict presented as current.

Report the split (n skipped, m triaged). A run that skips everything is the expected steady state, not a failure.

Phase 4 — Fan out

Take the issues that survived Phase 3 — including any item whose Status is empty, per Phase 2 — and run the workflow:

Workflow({ scriptPath: '.claude/workflows/triage-issues.js',
           args: { issues: [437, 434, ...], head: '<sha>', today: '<YYYY-MM-DD>' } })

Pass issues as a real array, not a JSON string — a stringified array reaches the script as one string and fans out per character. The script guards this, but the guard is a backstop, not a licence.

One read-only agent per issue. They report; only this skill writes. That separation is what keeps a parallel run from racing on the board.

If the workflow reports untriaged, those issues are unknown, not clean. Leave them in Backlog untouched and name them in the summary.

Phase 5 — Reconcile

The agents saw one issue each; the cross-issue judgements are yours.

• Dependencies. Build the dependsOn graph. A cycle means at least one edge is wrong — re-read both issues rather than picking one to break. An edge onto a closed issue is discharged; drop it.
• Contention. Two issues whose filesTouched overlap are not dependent, but landing them in parallel costs a rebase. Record it; it changes the order, not the status.
• Ready demotion. An issue is ready only if every issue it dependsOn is closed or also becoming Ready ahead of it. Otherwise it stays Backlog.
• Duplicates. Two wontfix/duplicate verdicts pointing at each other means neither agent saw the other. Keep the older issue, close the newer.

Phase 6 — Order

The ordering is computed, not composed. Run it:

python3 Scripts/build_run_list.py .build/run-list-input.json

Input is { head, ready, closed }. ready uses triage-issues.js' VERDICT_SCHEMA field names (issue, priority, size, dependsOn, filesTouched), so a freshly-triaged verdict is passed through untouched — re-shaping records by hand would put back, at the input, the transcription risk the script removes at the output. A skipped issue is assembled from its marker (issue, priority, size, dependsOn; it carries no filesTouched). closed lists the issues Phase 5 discharged edges onto.

It returns ordered, runListLine, and the three disclosures Phase 8 needs: depsOutrankPriority, dischargedEdges, unseparableContention.

An empty Ready set returns runListLine: null with a note saying why — deliberately, because a line with an empty issue list would parse as a well-formed run-list containing nothing, which is worse than no line at all. Publish the update without the line in that case, and carry the note.

The four sort rules — dependency order, priority, contention, size — are defined in Scripts/build_run_list.py, which is the copy that actually decides. Read them there; do not restate them here. That is the same single-ownership rule this file already applies to the rubrics, and for the same reason: a second copy drifted from the script within a day of being written. What is worth knowing without opening it: rule 1 outranks rule 2 (a P2 that unblocks a P0 goes first, which the script implements as effective priority — a plain topological sort does not do this), rule 2 outranks rule 3 (separating contenders never crosses a priority band), and contention is computed only over freshly-triaged issues because a marker carries no filesTouched.

Do not re-sort what it returns. Phase 8 pastes ordered and runListLine as they came back.

If it exits non-zero, it has found something Phase 5 should have resolved — a cycle, an edge onto an issue that is neither Ready nor closed, or a malformed record. Fix the input and re-invoke. Never hand-write the line: a hand-assembled line is the exact defect this phase was changed to remove. If it cannot be fixed this run, publish the status update without the line and say why — no line is honest, a wrong line is not.

Phase 7 — Write

Per issue, by exit:

Exit	Status	Also
ready	Ready	set Priority + Size
blocked	stays Backlog	add question label; comment leads with the decision needed
wontfix	close as not planned	add wontfix label; comment states the basis and cites the evidence
split	stays Backlog	comment proposes the split; do not create the child issues

Set Priority and Size on blocked and split items too — an unsized backlog item cannot be planned around. Only ready moves column.

split deliberately stops at a recommendation. Fanning one issue into six headless is a lot of tracker churn from a judgement call, and the split is usually obvious to a human in ten seconds.

Commenting — the idempotency rule

Headless on a schedule, a comment per issue per run makes the issues unreadable within a month. So:

• End every triage comment with the verdict's marker field, verbatim. The workflow script assembles it so the written form and the form Phase 3 parses cannot drift apart. Do not hand-build it.
• Read the last such marker before writing. Comment only if the evidenceDigest differs from the previous run. A new HEAD alone is not a reason to comment; nothing changed for the reader.
• When the digest is unchanged but HEAD has advanced, refresh the marker in place — edit the existing triage comment so its <sha> is current, rather than posting a new one. Without this the marker's sha only ever advances when a verdict changes, so in the steady state this skill is built for — main moves, verdicts do not — Phase 3's skip could never fire and every run would pay the full fan-out. The comment body stays as it was; only the marker moves.
• Write the marker comment last. Labels and field updates first, comment after — see Phase 3 condition 2. A label written after the comment makes the issue look touched-since-triage on the next run, and it re-triages forever.
• Field updates are always applied — they are idempotent and silent.

The digest and the marker are computed by the workflow script, not by the agent. The digest covers the decision-bearing fields only (exit, priority, size, wontfixBasis, sorted dependsOn, sorted staleClaims locations). Prose is deliberately excluded. Do not ask an agent for it and do not recompute it here: an LLM asked for a "stable fingerprint" will word the same findings differently each run, the digests will differ every time, and this rule quietly becomes a no-op that still looks enforced.

Comment content: what changed since filing, then corrected file:line pointers, then anything a picker-upper needs that the body lacks. Do not restate the issue back at its author.

Phase 8 — Publish the run-list

One Project status update per run — this is where execution order lives, since the board has no rank field:

mcp__github__projects_write / create_project_status_update
  status: ON_TRACK (or AT_RISK if anything P0 is blocked)

Body: the ordered Ready list (number, title, priority, size, one-line reason), then dependency edges, then contention warnings, then the Backlog-blocked items each with its one-sentence decision. Keep it scannable — it is read at a glance, and it is the diff between one run and the next.

The run-list line — paste what the script returned

End the body with Phase 6's runListLine, exactly as it came back, and nothing after it. Do not reword, prettify, annotate, wrap, or re-derive it — you are pasting a field, not writing to a format.

/deliver next parses that line and nothing else to decide what to work on (.claude/skills/deliver/references/next-mode.md §3). The prose table above it is for humans and is rewritten from scratch every run — the 2026-08-18 and 2026-08-20 updates already use different column headers and different cell formats, so anything parsing the table is parsing a moving target, and a near-miss would silently discard the dependency and contention ordering this phase exists to publish.

The grammar is defined by build_run_list_line in Scripts/build_run_list.py and parsed by RUN_LIST_RE in that same module, so the written form and the parsed form cannot drift apart — the same discipline as the per-issue marker, for the same reason. It is not restated here; if you need to see it, read it there.

A status update without the line is not a usable run-list. Attended, /deliver next says so and falls back to board fields — which reproduces two of Phase 6's four sort rules and loses the other two. Unattended, auto next and auto merge next stop outright, because a warning nobody reads is not a warning. So an omitted line does not merely degrade the next run; it can halt it.

Also carry, in prose, the three disclosures Phase 6 returns — they are facts the script supplies so this phase need not remember them:

• depsOutrankPriority — each case where a lower-priority issue precedes a higher one because it unblocks it. Say so, or the order reads as a mis-sort.
• unseparableContention — contending pairs left adjacent because nothing could sit between them.
• dischargedEdges — dependencies dropped because their target is closed.

Contention is computed only over freshly-triaged issues, since a marker carries no filesTouched. Say that, rather than implying full coverage.

Mark AT_RISK when a P0 sits in blocked: the highest-priority work being un-startable is exactly the state a status colour exists to surface.

Phase 9 — Report

To the caller: counts by exit, the ordered Ready list, every blocked item with its decision, anything closed and why, adopted orphans, and any untriaged issues. If nothing changed since the last run, say that plainly rather than padding — a quiet run is a good outcome, not a failed one.

Rules that do not bend

The Ready test. All four, every time: claims re-verified at HEAD; fix approach determined; no unmerged dependency; line references refreshed. A P0 that needs a decision is blocked. Priority never overrides the test — shipping someone into an unmade decision is worse than leaving it visible.

Wontfix is mechanical. no-longer-reproduces, superseded, duplicate. Nothing else. "Not worth doing" is a judgement a human takes; route it to blocked with the case made. A wrongly-ready issue costs twenty minutes; a wrongly-closed one is gone and nothing catches it.

Verify, do not trust. These issue bodies are written against older trees. Line numbers rot, whole mechanisms get replaced, ADRs land that decide the open question. An agent that reports without opening a file has not triaged anything — that is what verifiedBy is for, and "read the issue body" forces blocked.

Scope. Backlog only, plus the orphan sweep. Never touch In progress, In review or Done; someone is working there and a status change under them is hostile. Those three columns have owners of their own — /deliver sets In progress, /watch-pr sets In review, and the board's own automation sets Done; the whole lifecycle is tabulated in .github/ISSUE_FILING.md → Board status — the column lifecycle.

Rubrics

The rubrics live in .claude/workflows/triage-issues.js (RUBRIC) — that is the copy handed to every agent, so it is the one that actually reaches a decision. Read it there; do not restate it here. A second copy in this file drifted from the script within a day of being written, which is precisely the decay this repo's single-ownership rule exists to prevent.

What this skill owns and states above, because no agent needs it: the Ready test's four conditions, the wontfix bases, the four exits, and the skip rule.