Triaging

Overview

This playbook guides SDK maintainers through the triage process for incoming items — whether raised as GitHub issues or pull requests, reported via Discord or Slack, or surfaced through other channels. It covers monitoring intake channels, acknowledging new items, normalising them in Linear, and routing them to the correct outcome. By following these steps, all reported items receive timely, consistent responses and nothing stagnates in the queue.

Each repository MUST have a triage rotation in place that includes all maintainers (including contractors). The rotation MAY be daily or weekly depending on the team's needs. A designated triage owner MUST be accountable at any given time. All maintainers MUST be added to Linear triage notifications — single-maintainer repositories automatically assign items to the sole maintainer.

Triage SHOULD prioritise acknowledgement and categorization over immediate fixes.

Triage MAY be bypassed if the issue was created by a team member.

Related resources:

• Triaging SLA — 2 business day first response requirement
• GitHub Saved Replies — team-approved response templates for common scenarios
• Handling an External Contributor PR — PR-specific triage workflow
• Handling a Regression — regression response process

Steps

1. Monitor intake channels

Monitor the following channels daily:

• Linear SDK triage queue
• GitHub issues and PRs
• Discord and Slack SDK-related questions

Items MAY arrive through any of these channels. Social media is out of scope — redirect SDK questions to the monitored channels above.

2. Acknowledge new items

Response time expectations vary by channel:

• GitHub issues and PRs — initial response MUST be within 2 business days (Triaging SLA)
• Slack and Discord — response SHOULD be within a few hours during business hours

The response MUST acknowledge receipt and set expectations — a clarifying question, next steps, or a likely outcome. The initial response does not imply acceptance, prioritisation, or commitment to work.

Use the acknowledgement saved replies as a starting point.

3. Normalise the item

Before routing, ensure the item is properly recorded in Linear:

• If no associated Linear issue exists, one MUST be created — for Slack items, use the Slack–Linear integration to create the issue directly from the message
• If a duplicate exists, mark it as Duplicate of in Linear
• The Linear issue MUST have at least a Type label and an SDK label

4. Route the item

Every item MUST exit the triage queue via exactly one of the following paths:

Close as non-actionable — used when the item is clearly out of scope, invalid, or required clarification has not been provided within 7–14 days of the last response. Close the Linear issue with the appropriate status, link to documentation or alternatives where relevant, and include a brief explanation referencing any prior requests for information.

Resolve directly — used when the item is small, low risk, well understood, or high priority and can reasonably be addressed during triage. Resolve the item and update or close the Linear issue. Communication SHOULD briefly confirm the resolution and describe what was done.

Accept the item — used when the item requires further investigation, design, or implementation beyond triage. Move the Linear issue to Backlog or Todo and assign a priority, size estimate, and a clear problem statement with expected outcome. An assignee SHOULD NOT be set at this stage — assignment happens when the item is actively picked up (status: Todo or In Progress). Acknowledge acceptance and set expectations for next steps without committing to timelines unless known.

Escalate or reassign — used when the item requires broader discussion, different expertise, or clearly belongs to another team. Add a concise summary explaining the need for escalation or reassignment and transfer ownership. Communication MUST state why the item was escalated and who owns it next.

Prevent stagnation: escalate urgent issues and communicate unresolved issues promptly.

5. Respond to label states

Labels are applied automatically to reflect where action is required:

When an issue carries Waiting for: Product Owner, treat it as an active obligation in the triage queue — respond, investigate, or escalate within the SLA window. Labels reset automatically on each state transition.

See also: Waiting-for Labels

Referenced Standards

• Triaging SLA — 2 business day first response baseline and enforcement