How to Triage Issues With an Agent

Issue triage is the recurring process of turning incoming reports into clear next states: ready for an agent, ready for a human, waiting on more information, duplicate, archive, or rejected with a reason. The best triage makes the queue smaller without losing real bugs.

The work matters because untriaged issues hide both risk and opportunity. A confirmed bug waits beside a vague feature request, a duplicate, and browser noise, and every engineer has to re-read the same pile before choosing work.

Why issue queues quietly decay

Issue queues decay when classification and verification are treated as optional admin. Labels get applied from titles. Duplicates remain separate. Bugs are marked ready without reproduction. Noise gets archived without a reason, or left open because nobody wants to make the call.

The bundle's method turns triage into a state machine. Each issue gets one category, one proposed state, duplicate context, verification notes where needed, and a reason for any archive or rejection. Nothing is applied until a human approves the plan.

What the manual process looks like

Done by hand, a useful triage pass has a predictable shape:

1. Read the issue body, comments, prior labels, author context, and any linked pull request.
2. Search for duplicates, prior rejection, and existing behavior that already covers the request.
3. Classify the issue as a bug or enhancement.
4. Propose a state: needs triage, needs info, ready for agent, ready for human, or wontfix.
5. Verify actionable bugs by reproducing the reporter's steps or explaining why detail is insufficient.
6. Split oversized reports into thin, independently grabbable slices.
7. Draft a triage summary and apply changes only after approval.

The value is not just cleaner labels. It is a queue where the next person or agent can act without reconstructing the reasoning.

What an agent can automate

An agent can do the repetitive reading, checking, and summarizing while leaving queue-changing actions under review:

• Classify each issue. The agent applies a defined state machine and explains the category and proposed state for every item.
• Deduplicate by behavior. It searches for existing reports and implementations by domain concept, then links duplicates to a canonical issue.
• Verify before marking ready. For bugs, it attempts to reproduce the claim or marks the report as insufficient detail.
• Handle noise safely. It proposes archive-only actions for third-party noise, browser extension issues, single-event flukes, wrong-project reports, and similar categories, always with a reason.
• Split thick reports. When one report contains several independent problems, it proposes vertical slices with acceptance criteria and honest blocking order.

The agent proposes. It does not relabel, close, archive, or publish issue changes without approval.

The guardrails that make it safe

The first guardrail is the state machine. Every issue ends with exactly one category and one state, and conflicting signals cause the agent to stop and ask instead of forcing a label.

The second guardrail is approval. The workflow produces a triage summary table with counts, reasons, verification notes, label suggestions, routing, and archive proposals. The human approves the plan, a subset, or nothing. When in doubt, the agent skips the issue rather than burying a real bug.

Set it up in Task Machine

The Issue triage & routing playbook installs the Triage Agent, the Triage issues workflow, the no-backlog goal, three triage skills, and the schedule that runs the queue review. Setup takes a few minutes. You need a Task Machine workspace and permission to install playbooks (workspace owners have it). A connected repository is required for live issue access. Until it is authorized, use attached exports or a manual issue list for dry runs.

1. Find the playbook

Open Playbooks in your workspace and search for "issue triage", or browse the Engineering category. The card shows the Triage Agent, workflow, goal, skills, and schedule it creates.

2. Preview what it installs

Preview & install opens the install preview before anything is created. Review the Triage Agent, Triage issues workflow, issue-triage goal, frontend-noise, GitHub-triage, and issue-splitting skills, plus the weekday schedule.

3. Define the triage rules

Start setup asks for the repository, issue sources, routing labels, verification command, triage schedule, and timezone. Use the labels your team already uses for ownership and state, and choose a verification command that is safe for reproduced issues.

4. Generate and review

Generate customized playbook applies your repository and triage rules to the agent, workflow, goal, and schedule. In the review step, check that the workflow classifies and deduplicates, verifies actionable reports, drafts the triage summary, and waits for approval before issue changes are applied.

5. Install

Install customized playbook creates the issue triage workflow in your workspace. Two follow-ups arrive in your inbox: start Triage issues and set the issue-triage cadence. The first run reads the queue, proposes labels and routing, verifies actionable items, and waits for approval before anything changes in the issue tracker.

What good looks like

Good triage turns a queue into a set of next actions:

• Every issue has a reasoned state. Category, proposed state, and label changes are explained.
• Ready means verified. Bugs marked ready have reproduction notes or a clear reason why verification failed.
• Duplicates are linked. Related reports point to a canonical issue instead of creating parallel work.
• Noise is conservative. Archive proposals include reasons, and uncertain reports stay visible for human review.

Common questions

Can the agent close or archive issues by itself? No. It proposes changes and waits for approval before labels, routing, closure, or archive actions are applied.

What happens when an issue lacks enough detail? The agent should propose needs-info and draft specific questions for the reporter, not a vague request for more information.

Can it split one large issue into several smaller ones? Yes. The issue-splitting skill turns a thick report into thin vertical slices with acceptance criteria and blocking order.

What if the repository is not connected yet? The playbook can be reviewed and installed, but live triage needs repository access. Before that, use attached issue exports or sample reports for dry runs.