Issue Triage Workflow

Purpose: Evaluate, categorize, and route new issues to either the backlog or refinement queue.

Audience: Triagers, Project Management team, and contributors.

Status: Draft

Rationale

Triage is the critical decision point that determines whether an issue is ready for development or needs additional refinement. The triage process ensures that:

  • All issues have proper type and scope labels
  • Issues with sufficient detail go directly to the backlog with status::ready
  • Issues needing more information are routed to refinement with status::refine
  • Special labels (help-wanted, estimation-needed) are applied appropriately
  • Priority labels are not prematurely assigned (project manager handles them during sprint planning)

Effective triage keeps the backlog clean and ensures developers can pick up issues without confusion.

Quick Reference

Triage Decision: Is this issue clear enough to implement?

YES - Clear:

  • Has enough detail for a developer to start work
  • Technical requirements are understood
  • No additional investigation needed
  • Action: Add type/scope labels + status::ready, send to backlog

NO - Unclear:

  • Missing critical details
  • Requirements are vague or ambiguous
  • Needs investigation or research
  • Action: Add type/scope labels + status::refine, tag author and Product Manager

Labels Triagers Add:

  • ✅ type:: (if missing)
  • ✅ scope:: (all applicable scopes)
  • ✅ status::ready (if clear) OR status::refine (if unclear)
  • ✅ estimation-needed (optional)
  • ✅ help-wanted (optional)

Labels Triagers Do NOT Add:

  • ❌ priority:: labels (PM adds during sprint planning)

Analogy - Mass Casualty Incident:

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.

Workflow Steps

1. Identify Issues Needing Triage

Who: Triager, PM team, maintainers When: Regularly, multiple times per week Actions:

  • Check for issues with triage-needed label
  • Filter by: triage-needed label
  • Select oldest issues first (FIFO)

Result: List of issues ready for triage

2. Review Issue Content and Check for Duplicates

Who: Triager When: For each issue in triage queue Actions:

  • Verify template was used
  • Read the entire issue description
  • Check if all template sections are filled out
  • Understand what is being reported/requested
  • Search for potential duplicates:
    • Use key terms from the issue to search existing issues
    • Check both open and recently closed issues
    • Look for similar symptoms (for bugs) or requirements (for features)
    • If duplicate found, follow "Duplicate Issues" special case process and STOP triage

Result: Understanding of the issue's intent and completeness, confirmed not a duplicate

3. Add/Verify Type Label

Who: Triager When: During triage evaluation Actions:

  • If type:: label missing, add the appropriate one:
    • type::bug - Defect, something broken or not working as expected
    • type::enhancement - New feature or improvement to existing functionality
    • type::refactor - Code restructuring without changing functionality
    • type::question - Discussion or clarification needed
  • If type:: label present, verify it's correct
  • Change if creator selected wrong type

Result: Issue has correct type label

4. Add Scope Labels

Who: Triager When: After confirming type Actions:

  • Add one applicable scope:: label based on what parts of the system are affected:
    • scope::backend - Rust backend, API, database
    • scope::frontend - React/TypeScript UI, client-side
    • scope::CI - Pipeline, build process
    • scope::auth - Authentication, Keycloak
    • scope::e2e - End-to-end testing
    • scope::performance - Performance optimizations
    • scope::scraper - Data scraping tools
    • scope::nextcloud - Nextcloud integration
    • scope::pm - Project management processes
  • Prefer single scopes: Issues should ideally focus on one area
  • If issue is too broad and affects multiple scopes: Consider splitting it into separate issues, each with a single scope. Add a comment explaining the split and link the related issues together.
  • If scope is completely unclear: Do not add a scope label. Follow the "Cannot Determine Scope" special case process

Result: Issue has all relevant scope labels

5. Evaluate Issue Clarity

Who: Triager When: After adding type and scope Actions:

Ask: "Can a developer implement this without asking questions?"

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

  • Requirements are specific and actionable
  • For bugs: reproduction steps are clear
  • For features: use case and acceptance criteria are defined
  • Technical approach is straightforward
  • No investigation or research needed

Criteria for UNCLEAR (needs refinement):

  • Vague or ambiguous requirements
  • Missing reproduction steps (for bugs)
  • Unclear use case or acceptance criteria (for features)
  • Needs technical investigation
  • Multiple possible interpretations
  • Missing critical information

Result: Decision made on clarity

6. Route Issue

Who: Triager When: After clarity evaluation Actions:

If CLEAR:

  • Remove triage-needed label
  • Add status::ready label
  • Issue goes to backlog (ready for sprint planning)

If UNCLEAR:

  • Remove triage-needed label
  • Add status::refine label
  • Issue goes to refinement queue
  • Add comment explaining what needs clarification
  • Tag the issue author and Product Manager in the comment (e.g., @author @product_manager)

Result: Issue routed to backlog OR refinement queue

7. Add Optional Process Labels

Who: Triager When: During triage, as applicable Actions:

  • Add estimation-needed if:

    • Issue is clear but needs time estimation
    • Work sizing is required before sprint planning

  • Add help-wanted if:

    • Issue is suitable for community contributions
    • Good first issue for new contributors
    • Team needs assistance with this work

  • Add 1.0::must_have or 1.0::should_have if:

    • ONLY if you are Markus Raab
    • Never add these yourself without asking Markus first

  • Add other labels like:

    • documentation if it affects docs
    • usability if it's a UX concern

Result: Issue has all appropriate labels for its lifecycle

8. Remove Triage Label

Who: Triager When: After all triage steps complete Actions:

  • Verify all necessary labels are applied
  • Add comment if clarification or context would help

Result: Issue fully triaged and no longer in triage queue

Special Cases

Bug with Missing Reproduction Steps

If a bug report lacks clear reproduction steps:

  1. Add type::bug and appropriate scope:: labels
  2. Add status::refine label
  3. Add comment requesting specific reproduction steps and tag author and Product Manager
  4. Route to refinement queue

Feature Request with Vague Requirements

If a feature request is too broad or unclear:

  1. Add type::enhancement and appropriate scope:: labels
  2. Add status::refine label
  3. Add comment asking for specific use case and acceptance criteria, tag author and Product Manager
  4. Route to refinement queue

Cannot Determine Scope

If you truly cannot determine which part of the system is affected:

  1. Do NOT add a scope label
  2. Add status::refine label
  3. Add comment explaining why scope is unclear and what information is needed
  4. Tag the Product Manager

Duplicate Issues

If issue duplicates an existing issue:

  1. Add comment: "Duplicate of #XXXX" and tag the Product Manager
  2. Add duplicate label
  3. Notify Product Manager to close the issue
  4. Do NOT close the issue yourself (Product Manager handles closing)
  5. Do NOT complete rest of triage

Won't Fix / Invalid Issues

If issue is invalid, out of scope, or won't be fixed:

  1. Add comment explaining why and tag the Product Manager
  2. Add wontfix label
  3. Notify Product Manager to close the issue
  4. Do NOT close the issue yourself (Product Manager handles closing)
  5. Do NOT complete rest of triage

Examples

Example 1: Clear Bug - Goes to Backlog

Issue #1234: "Map editor crashes when adding Tomato plant"
- Complete reproduction steps provided
- Environment details included
- Expected vs actual behavior clear

Triage Actions:
1. Verify type::bug is set ✓
2. Add scope::frontend (crash in browser)
3. Evaluate: Can developer fix this? YES - steps are clear
4. Remove triage-needed and add status::ready
5. Do NOT add status::refine
6. Issue → Backlog

Result: Ready for sprint planning

Example 2: Unclear Feature - Goes to Refinement

Issue #1235: "Add better plant recommendations"
- Vague: what makes recommendations "better"?
- No acceptance criteria
- Multiple possible interpretations

Triage Actions:
1. Verify type::enhancement is set ✓
2. Add scope::backend
3. Evaluate: Can developer implement? NO - requirements unclear
4. Add status::refine
5. Remove triage-needed
6. Add comment: "@creator @product_manager Please clarify: What criteria should recommendations be based on? What defines a 'better' recommendation?"
7. Issue → Refinement queue

Result: Routed to refinement workflow

Example 3: Good First Issue

Issue #1237: "Add tooltip to explain map zoom controls"
- Clear requirements
- Small, focused change
- Good for new contributors

Triage Actions:
1. Verify type::enhancement ✓
2. Add scope::frontend
3. Evaluate: Clear? YES
4. Add help-wanted (good for community)
5. Remove triage-needed and add status::ready
6. Issue → Backlog

Result: Ready for sprint planning, flagged for new contributors
  • Issue Creation Workflow issue_creation.md - How issues are created before triage
  • Issue Refinement Workflow issue_refinement.md - What happens to issues with status::refine
  • Labels Documentation - Comprehensive label reference
  • GitLab Triage Board: Filter by scope::triage needed label

Troubleshooting

Common Issues

Problem: Unsure if issue is clear enough for backlog with status::ready Solution: When in doubt, add status::refine — better to over-refine than to send unclear issues to developers

Problem: Can't determine which scope labels to apply Solution: Route to refinement with status::refine without adding a scope label. Add a comment explaining what information is needed to determine the scope and tag the Product Manager

Problem: Issue is both a bug and feature request Solution: Split into two separate issues: one for the bug (type::bug) and one for the feature (type::enhancement). Link the issues together in the comments. People can still solve both in one MR if they choose, but having clear and minimal issues is preferred.

Problem: Issue needs immediate attention but no priority labels Solution: Do NOT add priority labels yourself. Notify PM team directly (GitLab/Nextcloud/Discord) and they will handle priority assignment during sprint planning

Problem: Template was not used Solution: Add comment requesting creator to use template. Explain triage tooling requires it

Open Points

  • Label definitions should be removed in the future and just link to the label definition file instead.
  • Need to clarify how to handle performance issues that need investigation (e.g., issues lacking profiling data where it's unclear if the problem is backend or frontend).

Notes

  • Do NOT add priority labels during triage — PM team adds these during sprint planning
  • Always tag author and Product Manager when adding status::refine to ensure they're notified and can provide clarification
  • Clear issues get status::ready and go to backlog; unclear issues get status::refine and go to refinement
  • Triage focuses on categorization and clarity, not urgency or importance
  • When in doubt, prefer adding status::refine over sending unclear issues to backlog with status::ready
  • Prefer single scope per issue — if an issue is too broad and affects multiple areas, consider splitting it into separate issues
  • Triage should be quick — if you spend more than 5 minutes, issue likely needs refinement