Docs Issue Triage

Docs Issue Triage Skill

This skill reads open GitHub issues in dbt-labs/docs.getdbt.com, scores them by priority and size using the definitions below, presents a ranked list to the user, and — with their confirmation — applies the appropriate labels directly to GitHub.

Step 1: Fetch open issues

Use the list_issues tool to fetch open issues from dbt-labs/docs.getdbt.com. Supported options:

• Limit by count: Use perPage to fetch a specific number (e.g. 10, 50, 100 max per request)
• Sort order: Use orderBy: CREATED_AT + direction: ASC for oldest-first, DESC for newest-first
• Pagination: Use the endCursor from pageInfo to fetch the next page

For each issue, collect:

• Issue number, title, and URL
• Body / description
• Existing labels (full list — needed for safe label merging in Step 4)
• Comment count
• Created date
• Updated date

Skip issues that already have both a priority: label AND a size: label — they've already been triaged. Track partially-labeled issues (priority but no size, or vice versa) separately — see Edge Cases.

Before proceeding to Step 4, verify that all triage labels exist in the repo by checking the known label set:

• priority: high, priority: medium, priority: low
• size: x-small, size: small, size: medium, size: large, size: x-large

If any label is missing from the repo, note it to the user before applying — do not create labels automatically.

Step 2: Score each issue

For each issue, assign one priority label and one size label based on the definitions below. Use the issue title, body, and any existing labels as signal. When in doubt, lean toward the more conservative (lower priority / smaller size) label and flag it for human review.

Priority Labels

| Label | When to apply |

|---|---|

| priority: high | Technical inaccuracy, missing or incorrect information, or broken links that negatively affect user workflows |

| priority: medium | Fix or enhancement to existing information that is generating customer requests or confusion |

| priority: low | Improvements that don't block workflows — grammar fixes, nice-to-haves, minor clarity improvements |

Priority signal heuristics:

• High comment count or many reactions → likely medium or high
• Words like "wrong", "broken", "404", "incorrect", "missing" in title/body → likely high
• Words like "typo", "grammar", "style", "suggestion" → likely low
• Customer-facing language or mentions of support tickets → likely medium or high

Size Labels

| Label | When to apply |

|---|---|

| size: x-small | Under 3 hours to fix (e.g. fix a typo, update a single code snippet, fix a broken link) |

| size: small | 1–2 days to address |

| size: medium | Up to a week to address |

| size: large | More than a week; may require more than one writer |

| size: x-large | 1+ weeks of research for 1+ writers — e.g. information architecture projects, major restructuring |

Size signal heuristics:

• Single broken link or typo → x-small
• One page needs updating → small
• Multiple related pages or a new section needed → medium
• New feature docs from scratch → large
• IA changes, navigation restructuring, multi-page rewrites → x-large

Step 3: Present ranked results

Present the triaged issues as a ranked table, sorted by priority (high → medium → low), then by age (oldest first within each priority tier).

Format:

## Triage Results — [date]

### 🔴 Priority: High
| # | Title | Suggested Size | Confidence | Notes |
|---|---|---|---|---|
| [#123](url) | Broken link in quickstart | x-small | High | 404 detected in title |
...

### 🟡 Priority: Medium
...

### 🟢 Priority: Low
...

### ⚠️ Partially Labeled (needs one dimension only)
| # | Title | Has | Needs | Suggested | Confidence | Notes |
|---|---|---|---|---|---|---|
| [#456](url) | Some issue | `size: small` | priority | `priority: medium` | High | Support ticket origin |
...

• Link each issue number to its GitHub URL (e.g. #123)
• Include a Confidence column (High / Medium / Low) to flag issues where the scoring is uncertain and human review is recommended before applying labels
• List partially-labeled issues in their own section so they're clearly distinguished

At the end of the table, ask:

> "Would you like me to apply these labels to GitHub? I can apply all of them, only the high-confidence ones, or you can tell me which specific issues to label."

Step 4: Apply labels (with confirmation only)

Never apply labels without explicit user confirmation. Once confirmed:

• For each confirmed issue, construct the full label list by merging the new triage labels into the issue's existing labels. Never pass only the new labels — this would strip all existing labels.
• Example: existing labels ["content", "improvement", "paper cut"] + new labels ["priority: medium", "size: small"] → pass ["content", "improvement", "paper cut", "priority: medium", "size: small"]
• Use issue_write with method: update and the merged label list.
• For partially-labeled issues, only add the missing dimension — preserve the existing triage label.
• Report back with a summary of what was applied and flag any failures.

Label names must exactly match:

• priority: high, priority: medium, priority: low
• size: x-small, size: small, size: medium, size: large, size: x-large

Edge cases

• Already partially labeled (has priority but not size, or vice versa): Score the missing dimension only, show in the dedicated partially-labeled section, and only apply the missing label.
• Ambiguous issues: If the issue is too vague to score confidently, assign a Low confidence rating and suggest the user review before applying.
• Large batch: If there are more than 50 un-triaged issues, offer to triage in batches by priority tier or by date range.