Triage Playbook

This playbook is for maintainers who intake, rewrite, prioritize, and decompose issues.

Triage objectives

  • turn vague requests into actionable work items

  • classify issues consistently

  • identify duplicates and overlaps early

  • connect execution issues to epics instead of embedding hierarchy in titles

New issue workflow

For each new issue:

  1. Confirm the title follows <type>(<area>): <concise outcome>. Rewrite it if needed.

  2. Confirm the issue body includes a problem statement, outcome, acceptance criteria, and test/docs impact.

  3. Apply labels across the required dimensions: type, area, priority, and status.

  4. Add size and risk labels when they improve planning clarity.

  5. Link the issue to an epic or initiative when the work is part of a larger stream.

If the issue lacks enough information to schedule work, move it to status:needs-info and request the missing details.

Required maintainer checks

Before an issue moves to status:ready, confirm:

  • the title is normalized

  • scope is clear

  • acceptance criteria are testable

  • dependencies or sequencing are documented

  • affected package and compatibility notes are present

  • docs impact is explicit, even if the answer is none

How to rewrite weak issues

When an issue is vague, rewrite the body into these sections:

  • Problem

  • Desired outcome

  • Constraints or non-goals

  • Acceptance criteria

  • Test impact

  • Docs impact

Move urgency and execution order out of the title and into labels or body notes.

Prioritization rubric

Use the following guidance when assigning priority:

priority:p0

Active production breakage, security impact, or a blocking regression.

priority:p1

Important correctness or maintainability work that should land in the next planned delivery window.

priority:p2

Valuable work that improves reliability, usability, or architecture but is not currently blocking other delivery.

priority:p3

Nice-to-have work, backlog grooming, or longer-range improvements.

Use risk:high for work that could affect public API compatibility, credential handling, concurrency, or critical transport logic.

Epic and sub-issue management

Use epics for multi-PR efforts that need coordinated delivery. Each epic should track:

  • objective

  • scope and non-goals

  • acceptance criteria

  • linked child issues

  • sequencing notes

Child issues should describe one implementable outcome each. Avoid titles such as [Step 1] or [Step 4] because sequencing may change as work evolves.

Duplicates and overlap

When two issues describe the same work:

  1. keep the clearer or more complete issue open

  2. link the duplicate to the surviving issue

  3. close the duplicate with an explanation

When two issues overlap but are not duplicates, clarify the split in both issue bodies and link them explicitly.

Blocked and stale issues

  • Use status:blocked when an issue cannot proceed because of an upstream dependency.

  • Use status:needs-info when the reporter or maintainer must provide more detail.

  • Revisit blocked or needs-info issues during backlog review instead of leaving them unlabeled.

Definition of done for triage

Triage is complete when the issue is either:

  • ready for implementation

  • waiting on information

  • marked blocked with a concrete dependency

  • closed as duplicate, invalid, or superseded

Triage should reduce ambiguity, not just add labels.