triage-issue

name: triage-issue description: Triage a GitHub issue by applying labels, setting project board fields, linking to epics, and identifying blockers.

Skill: Triage a GitHub Issue

When to use

After an issue is created (or discovered untriaged), apply the correct metadata so it's properly prioritized and discoverable on the project board.

Steps

1. Read the issue fully

Understand the scope, impact, and intent before triaging. Check for:

• Is it a duplicate of an existing open issue?
• Does it belong to an existing epic?
• Are there unresolved dependencies?

2. Apply type label

Every issue gets exactly one type label:

3. Apply component labels

Add one or more component labels based on which modules are affected:

4. Set priority

5. Set effort estimate

If effort is XL, consider whether the issue should be an epic with sub-issues instead.

6. Set phase

7. Link to epic (if applicable)

If the issue is part of a larger effort:

• Add **Parent**: <Epic title> to the issue body
• Use GitHub's sub-issues feature to link it under the epic
• Add **Depends on**: #N if there's a sequencing constraint

8. Check for blockers

If the issue depends on unfinished work:

• Add **Depends on**: #N to the body
• Apply the blocked label if the dependency is not yet in progress
• Set the project board status to Todo (not In Progress)

9. Position the item on the board

After setting all fields, assign a Stack Rank value and position the item in the correct location on the Task List view. The Stack Rank field is the canonical work order — new items land at the bottom by default and need to be assigned a proper rank.

1. Query the current board and sort by Stack Rank:

   gh project item-list 1 --owner lqdev --format json --limit 200
   

2. Sort items by Stack Rank ascending. Find the correct position based on the new item's Priority → Phase → Effort relative to existing items. The item should be placed:

   • After the last item with higher or equal priority (lower or equal Stack Rank number)
   • Before the first item with lower priority (higher Stack Rank number)
   • Above all epic/meta-epic items (features sort before their parent epics)

3. Compute a Stack Rank value between the surrounding items. For example, if inserting between rank 30 and 40, use 35.

   • If there is a gap (e.g., 30 and 40), pick a value in the gap (e.g., 35).
   • If there is no gap (the surrounding ranks are consecutive, e.g., 30 and 31), handle gap exhaustion explicitly:
     • Prefer: trigger the rerank-board skill to rebalance ranks for the affected section. It implements the gap-compaction and renumbering procedure.
     • For a small set of items only: increase the Stack Rank of the lower item and all items below it by +10 using gh project item-edit, then choose a value in the new gap (for example, between 30 and 40, use 35).

4. Set the Stack Rank field:

   gh project item-edit --project-id "PVT_kwHOAKnYPM4BPqK6" --id "<NEW_ITEM_ID>" --field-id "PVTF_lAHOAKnYPM4BPqK6zg-Gc20" --number <RANK>
   

5. Optionally sync physical board position with updateProjectV2ItemPosition:

   gh api graphql -f query='mutation {
     updateProjectV2ItemPosition(input: {
       projectId: "PVT_kwHOAKnYPM4BPqK6"
       itemId: "<NEW_ITEM_ID>"
       afterId: "<ITEM_THAT_SHOULD_COME_BEFORE>"
     }) { items(first:1) { nodes { id } } }
   }'
   

   If the item should be first on the board, omit afterId.

See the rerank-board skill for project constants and full reordering mechanics.

10. Apply status label (if needed)

Triage checklist

After triaging, the issue should have:

• Exactly one type label (bug, enhancement, documentation, or testing)
• One or more component labels (ui, storage, sync, etc.)
• Priority set on project board (P0–P3)
• Effort set on project board (XS–XL)
• Phase set on project board (or Backlog)
• Epic linkage if part of a larger effort
• Stack Rank assigned (not left at default / bottom)
• needs-triage label removed
• blocked label added if dependencies exist

Tips

• When in doubt about priority, check: "If we shipped tomorrow without this, would a user notice?" P0/P1 = yes, P2/P3 = probably not.
• Effort estimates are for a developer familiar with the codebase. Double it for a first-time contributor.
• Phase assignment follows the epic's phasing when the issue is a sub-issue. Standalone issues default to Backlog unless explicitly prioritized.