Issue Triage Guidelines

Principles and standards for evaluating and categorizing issues during triage.

Triage Philosophy

Medical Triage Analogy

Think of issue triage like medical triage at a mass casualty incident where emergency responders evaluate multiple patients:

• Needs acute attention first (🚨 Immediate Care) → Issues with status::refine

  • Patient needs stabilization, diagnosis, or additional assessment before transport
  • Similarly, unclear issues need clarification, investigation, or additional information before developers can work on them
  • Route to: Refinement workflow where PM and author provide missing details

• Can be transported (🚑 Stable for Transport) → Issues with status::ready

  • Patient is stable with clear diagnosis, ready to be transported to appropriate facility
  • Similarly, clear issues with complete requirements are ready to be picked up by developers
  • Route to: Backlog for sprint planning and implementation

Just as medical triage doesn't decide which hospital or prioritize ambulance routing (that comes later), issue triage focuses only on clarity assessment — not priority or sprint assignment.

Clarity Assessment

The Key Question

"Can a developer implement this without asking questions?"

This is the fundamental question that determines whether an issue goes to the backlog or needs refinement.

Criteria for CLEAR (ready for backlog with status::ready)

An issue is clear when:

• Requirements are specific and actionable

  • Developer knows exactly what needs to be built or fixed
  • Success criteria are unambiguous
  • No room for multiple interpretations

• For bugs: reproduction steps are clear

  • Step-by-step instructions to reproduce the issue
  • Expected vs. actual behavior is documented
  • Environment details are provided (OS, browser, versions, etc.)
  • Error messages or logs are included when relevant

• For features: use case and acceptance criteria are defined

  • Clear problem statement or user need
  • Description of desired functionality
  • Specific acceptance criteria defining "done"
  • User stories or scenarios provided

• Technical approach is straightforward

  • Implementation path is obvious
  • No significant technical unknowns
  • Required changes are well-scoped

• No investigation or research needed

  • All information necessary to start work is present
  • Dependencies are identified
  • No ambiguous requirements

Criteria for UNCLEAR (needs refinement)

An issue needs refinement when:

• Vague or ambiguous requirements

  • Multiple possible interpretations
  • Unclear what "done" looks like
  • Abstract or high-level descriptions without specifics

• Missing reproduction steps (for bugs)

  • Cannot reliably reproduce the issue
  • Environment details missing
  • Unclear when/where the bug occurs

• Unclear use case or acceptance criteria (for features)

  • No clear problem statement
  • User need not articulated
  • Success criteria undefined or subjective

• Needs technical investigation

  • Performance issues without profiling data
  • Root cause is unknown
  • Requires research or experimentation
  • Technical feasibility unclear

• Multiple possible interpretations

  • Different developers might implement differently
  • Design decisions needed
  • Ambiguous terminology

• Missing critical information

  • Key details omitted from description
  • Unclear scope or boundaries
  • Related issues or dependencies not identified

Decision Making

When in Doubt

• Prefer adding status::refine over sending unclear issues to backlog
  • Better to over-refine than to send unclear issues to developers
  • Refinement process can always promote issues quickly if they're actually clear
  • Unclear issues in the backlog waste developer time and cause frustration

Common Pitfalls to Avoid

• Don't confuse importance with clarity

  • An urgent issue can still be unclear
  • Priority is determined during sprint planning, not triage

• Don't add scope labels if truly unclear

  • If you can't determine which part of the system is affected, route to refinement
  • Add comment explaining what information is needed

• Don't spend too long on triage

  • Triage should be quick (5 minutes max per issue)
  • If you're spending more time, the issue likely needs refinement

Labeling Best Practices

Scope Labels

• Prefer single scope per issue

  • Issues should ideally focus on one area of the system
  • Single scope makes assignment and estimation easier
  • Reduces complexity and potential for confusion

• If issue affects multiple scopes

  • Consider splitting into separate issues, each with a single scope
  • Add comment explaining the split
  • Link related issues together
  • Note: People can still solve multiple issues in one MR if appropriate

Process Labels

• Add optional labels judiciously

  • estimation-needed: Issue is clear but needs time estimation
  • help-wanted: Suitable for community contributions or new contributors
  • 1.0::must_have or 1.0::should_have: ONLY if you are Markus Raab

• Do NOT add priority labels

  • Priority is PM's responsibility during sprint planning
  • Triage focuses on clarity, not urgency

Quality Standards

Thoroughness

• Search for duplicates before completing triage

  • Use key terms to search existing issues
  • Check both open and recently closed issues
  • Look for similar symptoms (bugs) or requirements (features)

• Verify template usage

  • Templates are required for triage tooling
  • Request creator to use template if missing
  • Proper template structure aids in clarity assessment

Communication

• When routing to refinement

  • Add comment starting with: "⚠️ Triage in Progress - Clarification Needed"
  • Explain specifically what needs clarification
  • Tag the issue author and Product Manager
  • Be helpful and constructive in your feedback

• Always tag relevant people

  • Author: To provide additional information
  • Product Manager: To provide product context and decisions
  • Use format: @author @product_manager