triage: Turn Backlog Mess Into Agent-Ready Work

Most skill-based setups work great for solo developers. But when you move into teams, or start building for other people, everything changes.

You need to triage other people's ideas. Figure out if they're worth building. Determine if it's a bug report. Decide if you need to reproduce it. This is familiar to anyone who's built anything of reasonable size.

Introducing Triage

I built a skill called /triage to handle exactly this. I run it on every single open source repo I maintain.

Where /triage works:

• GitHub issues
• Jira
• Any backlog system

It turns messy backlog items into actionable tasks that agents can pick up, reject, or process.

The State Machine Approach

The power of /triage comes from encoding a state machine into labels. There are two category roles:

Then there are five state roles that track where a ticket is in its lifecycle:

This is a proper state machine. Every triaged issue carries exactly one category role and one state role. You can't have something be "ready for human" and "needs triage" at the same time.

How to Use Triage

There are several ways to use this skill:

• Triage a specific issue
• Triage the entire backlog and show only items needing your attention
• Move a specific issue to a new state (like ready-for-agent)
• Create an agent brief for tasks moving to ready-for-agent

Seeing It in Action

Let's triage a real repo. I'll open a new Claude session and ask it to handle untriaged issues:

/triage

Just give me all of the open issues that I haven't triaged yet.

The agent explores the repo, detects GitHub issues, and identifies nine untriaged open issues.

Then I ask:

Could you just walk through each of these and add the basic labels to them?
Just doing initial triage for me so that I don't need to make that many decisions.

The agent labels everything with appropriate categories and marks them all as needs-triage.

Using Out-of-Scope Files

How does the agent know what can actually be built? Inside the repo, there's a .out-of-scope directory containing architectural decision records for features we're not implementing.

For example, this file might say:

Sandcastle does not provide an abstraction layer for composing docker files or managing base images programmatically.

When the agent reviews enhancement issues, it checks these out-of-scope documents. If an issue matches something we've already decided not to build, the agent can close it immediately.

Working Through Issues

Let's tackle the bugs first. I ask about issue #477:

Could you start with 477 for me?

The agent recommends moving it to ready-for-agent. It already has substantial triage notes with the exact root cause and a stack trace.

But I want the agent to reproduce it itself rather than trust the reporter completely. So I ask it to diagnose the bug:

Could you diagnose this yourself?

This makes the agent walk through reproducing the bug and attempting to fix it.

I keep an eye on context usage. We're at 46.5k of 100k tokens - plenty of room to diagnose and fix this.

Diagnosis Confirmed

The agent finds the issue: a couple of variables contain literal task IDs. When this syntax isn't passed in by the user, it causes an error.

The fix is simple: replace those task IDs with a placeholder pattern that won't trigger an error.

The agent also adds a unit test to prevent regression:

The /diagnose skill uses a similar pattern to the TDD skill: create the regression test first, then fix the bug within that feedback loop.

Fixing and Pushing

Once the issue is diagnosed, I can fix it right there in the session. I approve the command and put it into auto mode.

The agent pushes the fix to main and closes the original issue.

(Alternatively, I could have it create a PR that references the issue, so merging the PR automatically closes it - that's how I usually prefer to work.)

Next Steps

Want to dive deeper? Check out the skills page on AI Hero where I post all the changelogs - both video and article - so you can keep up to date.