Read-Only Constraint
IMPORTANT: This skill performs READ-ONLY operations. Never use:
-
gh issue edit , gh issue close , gh pr merge
-
gh api -X POST/PUT/PATCH/DELETE
-
Any command that modifies issues, PRs, or labels
Report findings to the user; let them decide what actions to take.
Issue/PR Triage
Triage a GitHub issue or pull request by analyzing duplicates, documentation alignment, project fit, and recommending labels.
Usage
/triage <issue-or-pr-number>
Workflow
- Fetch the Issue/PR
Use GitHub CLI to get full details:
For issues
gh issue view <number> --json number,title,body,labels,state,author,createdAt
For PRs
gh pr view <number> --json number,title,body,labels,state,author,createdAt,files,additions,deletions
Determine the type based on content: bug report, feature request, question, documentation issue, or pull request.
- Duplicate and Prior Decision Search
Search for related closed issues and discussions:
Search closed issues with relevant labels
gh issue list --state closed --label wontfix --search "<keywords>" --limit 10 gh issue list --state closed --label duplicate --search "<keywords>" --limit 10 gh issue list --state closed --label invalid --search "<keywords>" --limit 10
General search across all issues
gh search issues "<keywords>" --repo peteonrails/voxtype --limit 15
Search discussions for prior decisions
gh api repos/peteonrails/voxtype/discussions --jq '.[].title' 2>/dev/null || echo "No discussions API access"
Extract 3-5 keywords from the issue title and body for searching.
- Related PR Search
Find open PRs that might address this issue:
gh pr list --state open --search "<keywords>" --limit 10
- Documentation Check
Read relevant documentation to determine if user misunderstands setup or configuration:
-
README.md
-
Installation and quick start
-
docs/TROUBLESHOOTING.md
-
Common issues and solutions
-
docs/CONFIGURATION.md
-
Config file options
-
docs/PARAKEET.md
-
Parakeet-specific setup (experimental)
-
docs/MODEL_SELECTION_GUIDE.md
-
Model and engine selection
If the reported issue is actually documented expected behavior or a setup mistake, note this in the report.
- Project Fit Assessment
Read CLAUDE.md sections on Project Principles and Non-Goals.
Project Principles (all work should align with these):
-
Dead simple user experience
-
Backwards compatibility
-
Performance first
-
Excellent CLI help
-
Every option configurable everywhere
-
Documentation in the right places
Non-Goals (requests for these should be declined):
-
Windows/macOS support (Linux-first, Wayland-native)
-
GUI configuration (CLI and config file are the interface)
Also check:
-
Issues/discussions closed with decisions against similar features
-
CLAUDE.md roadmap for what's planned vs out of scope
- PR Quality Assessment (PRs only)
For pull requests, additionally assess:
-
Linked issue: Does it reference an issue? Is that issue valid?
-
Scope: Does it do exactly what the linked issue asks, or does it include scope creep?
-
Code style: Does it follow conventions in CLAUDE.md?
-
Tests: Are there tests for new functionality?
-
Documentation: Are user-facing changes documented?
-
Breaking changes: Does it break backwards compatibility?
- Label Recommendation
Based on analysis, recommend appropriate labels from:
Label When to Apply
bug
Confirmed bug in existing functionality
enhancement
Feature request or improvement
documentation
Documentation issue or improvement
question
User asking for help, not reporting a bug
duplicate
Already reported in another issue
invalid
Not a valid issue (spam, off-topic, etc.)
wontfix
Valid but won't be addressed (non-goal, out of scope)
good first issue
Well-defined, isolated, good for newcomers
help wanted
Needs community contribution
deb
Related to Debian packaging
rpm
Related to RPM packaging
aur
Related to AUR source package
aur-bin
Related to AUR binary package
nixos
Related to NixOS packaging
omarchy
Related to Omarchy distribution
Apply multiple labels when appropriate (e.g., bug
- deb for a Debian-specific bug).
Output Format
Generate a triage report with this structure:
Triage Report: #<number> "<title>"
Type: Bug / Enhancement / Question / PR Author: @username Created: YYYY-MM-DD
Summary
Brief description of what the issue/PR is about.
Duplicate Check
- No duplicates found OR
- Similar: #XX "title" (closed, wontfix) - brief reason
- Related: #YY "title" (open) - how it relates
Documentation Check
- Not a documentation/setup issue OR
- This appears to be a setup issue. docs/TROUBLESHOOTING.md section "XYZ" addresses this.
- User may be misunderstanding [specific feature/behavior].
Project Fit
- Aligns with project goals OR
- Conflicts with non-goal: [specific non-goal]
- Conflicts with principle: [specific principle]
PR Quality (if applicable)
- Linked issue: #XX or "None"
- Scope: Appropriate / Contains scope creep
- Code style: Follows conventions / Issues noted
- Tests: Present / Missing
- Breaking changes: None / Yes - [description]
Recommended Labels
label1, label2, label3
Suggested Action
- Close as duplicate of #XX
- Close as wontfix (non-goal)
- Request more information from author
- Ready for review
- Needs documentation update before merge
- Add to backlog
- etc.
Commands Reference
View issue details
gh issue view 123 --json number,title,body,labels,state,author,createdAt
View PR with changed files
gh pr view 123 --json number,title,body,labels,state,author,files
Search issues by keyword
gh search issues "audio pipewire" --repo peteonrails/voxtype
List issues by label
gh issue list --label bug --state open
List closed wontfix issues
gh issue list --state closed --label wontfix --limit 20
Add labels (reference only - report to user, don't auto-apply)
gh issue edit 123 --add-label "bug,deb"
Close with comment (reference only)
gh issue close 123 --comment "Closing as duplicate of #XX"