agentleFS
pooriaarabpooriaarab/skills/backlog-triage/SKILL.md

backlog-triage

Skill1 starsChanged 9 days agoMITView on GitHub

Act as the product manager for an open GitHub backlog. Decide what blocks the next release, give every open issue one priority, correct its state and routing labels, and append an implementation brief that a cheap model can execute without asking anything: where in the code, steps in order, decisions already made, edge cases, pre-work research, skills and reference URLs, and what done means. Researches in parallel and writes in a second pass so priorities are calibrated across the whole backlog. Re-runnable: the brief sits between markers and is replaced, never stacked. Triggers include \"triage the backlog\", \"what is blocking release\", \"prioritise the issues\", \"enrich the issues so any model can do them\".

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 10 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before a release cut, to name the release blockers.

    line 14
  2. Distinctive:

    When the backlog has grown past what one person reads in a sitting.

    line 15
  3. Distinctive:

    When issues are routed to cheap or fast models and keep coming back with questions, wrong files touched, or the same gotcha hit twice.

    line 16
  4. Very specific:

    NOT for writing one spec from a thin ticket (use spec-issue).

    line 18
  5. Very specific:

    NOT for raw bug-bash notes (use bug-bash-triage).

    line 19
  6. Very specific:

    A release-blocker label: when, and only when, the rubric says so.

    line 24
  7. Very specific:

    Read the repo's own process before touching a label: AGENTS.md, any issue standard (.agents/issues.md, CONTRIBUTING.md), the issue …

    line 36
  8. Distinctive:

    Write the rubric to a file before any research starts.

    line 50
  9. Very specific:

    Checks whether the work is already done: Search merged PRs for the issue number and grep the code for the feature.

    line 100
  10. Distinctive:

    Read every agent's summary lines together.

    line 123
  11. Distinctive:

    Read the current body fresh.

    line 142
  12. Distinctive:

    If the markers already exist, replace what is between them.

    line 143
  13. Distinctive:

    Updating labels replaces them: Always send the full intended set.

    line 243
  14. Distinctive:

    Do not write "Parent: #N" or "Blocked by: #N" in prose: when the tracker has native sub-issues and dependencies.

    line 248
  15. Distinctive:

    Every open issue has exactly one priority label and one label per group.

    line 257

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

backlog-triage

Turn an open backlog into a ranked, release-aware queue where each issue carries enough direction that the cheapest capable model can pick it up and finish it.

When to use

  • Before a release cut, to name the release blockers.
  • When the backlog has grown past what one person reads in a sitting.
  • When issues are routed to cheap or fast models and keep coming back with questions, wrong files touched, or the same gotcha hit twice.
  • NOT for writing one spec from a thin ticket (use spec-issue).
  • NOT for raw bug-bash notes (use bug-bash-triage).

The output, per issue

  1. Exactly one priority label. priority:p0, priority:p1, priority:p2.
  2. A release-blocker label when, and only when, the rubric says so.
  3. Corrected labels. Exactly one from each group the repo defines, such as kind, size, route and state. Fix contradictions. Fill in what is missing.
  4. A brief appended to the issue body between <!-- pm-triage:start --> and <!-- pm-triage:end -->. The original body above the markers is never edited.

Plus one backlog summary for the owner: the release blockers, the ordered p1 queue, the owner questions, and the issues that are already done.

Stage 0: read the house rules first

Read the repo's own process before touching a label: AGENTS.md, any issue standard (.agents/issues.md, CONTRIBUTING.md), the issue templates, and the release gate document if one exists (a release checklist, a golden path, a smoke-test list). Use the repo's labels. Check which priority labels exist before applying one, because an API that auto-creates a label on first use will spawn a typo'd duplicate silently.

Define "release" from the repo, not from habit. Find which branch ships to production and what gate it passes. The release blocker rubric hangs off that gate. If there is no written gate, write the one-sentence definition you are using into the backlog summary, so the owner can correct it.

Stage 1: the rubric

Write the rubric to a file before any research starts. Every research agent reads the same file. Without it, five agents produce five priority scales and the calibration pass becomes a rewrite.

Release blocker: any one of

  1. It breaks or degrades a step of the release gate (golden path, smoke list).
  2. It loses data or silently overwrites a user's work.
  3. It is a security, auth or tenant-isolation hole.
  4. It moves money wrongly, and that money path is reachable by real users today. Verify reachability in code and config. A bug in a test-mode-only flow is a p1, not a blocker.
  5. It breaks a flow users already have. A missing new feature is not a blocker. Visual parity is not a blocker.

Priority

LabelMeaning
priority:p0A release blocker, or the owner set p0. Never downgrade an owner's p0.
priority:p1Do next. Unblocks a p0, sits on the owner's declared critical path, or a real user can hit the defect today.
priority:p2Valuable, after p1. Polish, parity, research, new surfaces.

Be stingy with p0. If more than about a tenth of the backlog is p0, the scale has stopped meaning anything. Re-read the rubric and demote.

State

StateOnly when
ready-for-agentA cheap model could start today. No open blocker, no owner decision.
blockedA named open issue or PR must land first. Name it.
needs-infoAn owner decision is required. Write the question and a recommended answer.
triageAvoid. It means the triager did not decide.

High-stakes paths (auth, billing, public API tenant scope, the deploy or publish path, database migrations) route to the judgement tier whatever the size.

Stage 2: research in parallel, read-only

Cluster the backlog by surface (billing, mail, editor, one epic's children) and give each cluster to one research agent. Seven to twelve issues per agent works. Fewer agents than that and the context fills before the cluster is done. More and the cross-issue view inside a cluster is lost.

Each agent, per issue:

  1. Reads the full body and all comments. Owner decisions often live only in a comment. For an epic, also reads the sub-issues and their state.
  2. Checks whether the work is already done. Search merged PRs for the issue number and grep the code for the feature. An issue closed by a merge that forgot Closes # is the most common stale entry. Flag it as a close candidate. Do not close it from the research pass.
  3. Checks for an open PR already on the issue, so nobody duplicates it.
  4. Greps the codebase. Every path cited must exist. Verify with ls or grep, and cite file:line. A brief that points a cheap model at a file that does not exist is worse than no brief, because the model will create it.
  5. Finds reference material: design docs, research notes, screenshots, recordings, and the vendor's docs page for any third-party API involved.
  6. Writes the brief to a local file, briefs/<issue>.md, and returns one compact line per issue:
#N | p1 | blocker n | state ready-for-agent -> blocked (#M) | add size:standard | why | CLOSE-CANDIDATE?

Nothing is written to the tracker in this stage. Research is reversible; a label flip that triggers an agent pickup is not.

Stage 3: calibrate across the backlog

Read every agent's summary lines together. This is the PM's job and is not delegated.

  • Count the p0s. Demote anything that does not meet the rubric literally.
  • Check dependencies across clusters. A mail issue blocked on an editor issue is invisible from inside either cluster.
  • Find duplicates and keep the one with the better acceptance criteria.
  • Order the p1 queue. Blockers first, then whatever unblocks the most other issues, then the owner's critical path.
  • Collect owner questions into one list, each with a recommended answer, so the owner can answer them all in one sitting.

Then tell each research agent the calibrated values that changed, and have it correct its brief before anything is written.

Stage 4: write

For each issue:

  1. Read the current body fresh. Someone may have edited it since research.
  2. If the markers already exist, replace what is between them. Otherwise append the block after a blank line. Never touch text above the markers.
  3. Set labels in the same update, as a full list. A partial label list on an update replaces the existing labels and drops kind or size.
  4. Close candidates get a comment naming the commit on the default branch, not a silent close, and only when the owner asked for closes. Otherwise list them in the summary for the owner to close. Closing is the one write a permission layer is most likely to refuse, so plan for it to be handed back.
  5. Fix native dependencies the research found wrong. Common cases: an inverted pair, an epic listed as a blocker of its own children (it can never clear), and a blocker that is already done.

The brief template

Dense, imperative, concrete. About 70 lines at most. Leave out a section only when it is truly empty, because an empty heading reads as answered.

<!-- pm-triage:start -->
## Triage brief
**Priority:** P1 — <one-line why>. **Release blocker:** No — <why>.
**Start now?** Yes | No — <what must happen first: #issue, PR, or owner decision>.

### Where to work
- `path/to/file.ts:123` — what lives here and why it matters.

### Do this, in order
1. ...

### Decisions already made (do not reopen)
- ...

### Edge cases and gotchas
- ...

### Pre-work research (only if needed)
- The question, where to look, and what to produce before coding.

### Resources
- Skills: the skills the implementer should load, by exact name.
- References: research notes, screenshot paths, vendor docs URLs.

### Done means
- [ ] A testable check tied to an acceptance criterion.
- Verify: exact commands, the exact test file or config, and the preview walk
  if a user can see the change.

### Owner question
- The question, the recommended answer, and the trade-off.
<!-- pm-triage:end -->

What makes a brief usable by a cheap model

  • Name the file, the function and the line. "The header component" sends a cheap model searching and it settles on the first match.
  • Write the order of steps. Cheap models do the interesting step first and skip the migration or the test.
  • Write the decisions down as decisions. Anything phrased as an option will be reopened.
  • Name the trap. The thing that broke the last attempt goes in gotchas, with the issue or PR number where it happened.
  • Give the verification as a command. "Test it" means nothing. Write bun run ci:local, then the one Playwright config that covers the surface.
  • Point at a skill by its exact name and at the vendor doc by URL. For visual or UI fidelity work, point at a design-review skill and impeccable.style for its audit and polish passes. For billing, the payment provider's webhook and API reference pages. For a third-party fetch of user URLs, the SSRF rules.

Gotchas

  • "Merged" does not mean "on main". In stacked-PR repos, a child PR merged into its parent's branch after the parent was already squash-merged lands nowhere. The PR page says merged, the issue stays open, and the code is not shipped. In one run, 28 PRs merged inside a three-minute window had this shape, and 16 open issues were "done" only on dead branches. For every PR cited as evidence, check git merge-base --is-ancestor <merge_sha> origin/main. A stranded PR's branch still holds the work, so the brief names the SHA to port and says to port by hand, because the base has moved. File one audit issue for the whole stranded set, so it is fixed once and not rediscovered issue by issue.
  • The reverse also happens. An issue whose own PR is stranded can still be done, because a later squash carried the same change in. Check the code on the default branch, not the PR.
  • "Closed" does not mean "done" either. A parent issue closed when only half its job shipped is the root cause of a new bug. Say so in the brief, so the implementer does not trust the closed issue's description of the system.
  • The backlog moves while you research. New issues, new dependencies and new PRs appear during a long research pass. Before writing, re-read each issue's blockers, and list open PRs again. The issues endpoint returns PRs as well, so filter them out.
  • Reference material that lives on one machine is not reference material. Briefs that cite /tmp/... captures from another host send the implementer looking for files that do not exist. Name the fallback in order: numbers in the issue and specs, committed screenshots, then a fresh capture.
  • The owner's word beats the rubric. An owner-set p0, or a comment saying "this comes first", stays. Note the disagreement in the summary if there is one. Do not overwrite it.
  • Updating labels replaces them. Always send the full intended set.
  • Issue bodies have a size limit. GitHub caps a body at 65,536 characters. A long body plus a brief can hit it. Check the length before writing. If it would overflow, post the brief as a comment carrying the same markers and link it from one line inside the body markers.
  • Do not write "Parent: #N" or "Blocked by: #N" in prose when the tracker has native sub-issues and dependencies. Use the native relation.
  • A merged PR is the evidence for "done", not a commit message. Check the PR closed the issue, or that the code is on the default branch.
  • Re-running is the point. Because the brief sits between markers, the next triage replaces it. Date the brief so a reader can tell how stale it is.

Verify the run

  • Every open issue has exactly one priority label and one label per group. Query the tracker and count. Do not trust the write loop's success output.
  • The p0 list matches the release blocker list plus any owner-set p0s.
  • Spot-check three briefs at random: open each cited path, and run one verification command.
  • The backlog summary reaches the owner with the blockers, the ordered p1 queue, the owner questions and the close candidates.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.