github-issue-triage
Use only when the user explicitly invokes $github-issue-triage or names github-issue-triage. Triage open GitHub issues in the current repository, recommend the next issue to handle, and identify safe
SKILL.mdskills/local/github-issue-triage/SKILL.md
GitHubGitHub Issue Triage
Scope
Use this skill to answer questions like:
- Which open GitHub issue should we handle next?
- Which issues can be worked on in parallel?
- Which issues are blocked, parent trackers, or future-scope work?
This skill is for current-repository triage only. It recommends work; it does not start implementation.
Workflow
- Resolve the current repository from local git context.
- Confirm the branch and dirty state with
git status --short --branch. - List other worktrees with
git worktree list --porcelain, and map each to an issue number when its branch or path names one; report the rest as unmapped. - Resolve the GitHub repository with
gh repo view --json nameWithOwner,url,defaultBranchRef.
- Confirm the branch and dirty state with
- Fetch the current GitHub state.
- List open issues with
gh issue list --state open --limit 100 --json number,title,labels,assignees,updatedAt,createdAt,url. - List open pull requests with
gh pr list --state open --limit 50 --json number,title,headRefName,baseRefName,labels,updatedAt,url. - For each plausible work issue, fetch details with
gh issue view <number> --json number,title,body,labels,comments,url,state. - Collect each issue's dependencies from
Blocked by #<n>lines in its body and from GitHub's native relationships:gh api repos/<owner>/<repo>/issues/<number>/dependencies/blocked_byand, for trackers,gh api repos/<owner>/<repo>/issues/<number>/sub_issues. - If a relationship API is unavailable or fails, use the body lines alone and mention that native relationships could not be read.
- Collect each issue's
Touched Areassection when present. - For open PRs that may overlap with candidate issues, fetch changed files with
gh pr view <number> --json files.
- List open issues with
- Read local repository guidance before ranking.
- Check project instructions such as
AGENTS.md. - Check product or roadmap docs if present, commonly
README.md,docs/*.md,WORKFLOW.md, or milestone docs. - Use this context to filter out work that violates product scope or repository rules.
- Check project instructions such as
- Classify each open issue.
- Parent tracker or milestone issue.
- Directly actionable implementation issue.
- Blocked by another issue or PR. Treat an issue as blocked while any of its blocking issues is still open, whether the dependency came from a
Blocked by #<n>line or a native relationship. - If body lines and native relationships disagree, use their union and note the disagreement.
- Future-scope or out-of-scope work.
- Duplicate or already represented by an open PR.
- Already in progress in another local worktree.
- Rank actionable issues.
- Prefer issues that unblock later work, especially precursor issues that settle a contract for several blocked issues.
- Prefer work aligned with current product direction and repository instructions.
- Prefer clear acceptance criteria and moderate blast radius.
- Defer broad, ambiguous, high-risk, or future-scope work unless it is explicitly the priority.
- Treat parent tracking issues as coordination items, not the next coding task, unless all children are complete.
- Identify parallel work candidates.
- Build the current wave: actionable issues that have no open blocking issues.
- Within the current wave, group issues as parallel only when their touched areas do not overlap, including shared resources such as schemas, config, migrations, lockfiles, or public interfaces.
- Also check each candidate's touched areas against the changed files of open PRs, and flag overlaps as conflicts with in-flight work.
- For other worktrees that may overlap candidates, list changed files with
git -C <path> diff --name-only <default-branch>...HEADandgit -C <path> status --short, and flag overlaps the same way. Skip worktrees with no changes. - When an issue has no
Touched Areassection, infer its likely areas from the body and repository, and label them as inferred. - Do not recommend parallel work when one issue defines policy, schema, or workflow behavior that another issue depends on.
- Mention likely conflict areas such as shared config modules, schemas, migrations, job orchestration, or the same UI files.
- Recommend the next step without starting work.
- Give exactly one best next issue.
- If useful, suggest the follow-up command, for example
$github-issue-start #23.
Output Format
Use this structure:
**Current State**
- Open issues: <count>
- Open PRs: <count>
- Active worktrees: <count, mapped issues>
- Local branch/state: <short note>
**Recommended Order**
| Rank | Issue | Recommendation | Reason |
|---|---|---|---|
| 1 | #<n> <title> | Do next | <why> |
**Parallel Work**
- Current wave: #<a>, #<b> (<parallel groups, or why they must not run together>)
- Overlaps: <touched-area overlaps between issues or with open PRs or worktrees, or "none">
- Next wave after #<n> closes: #<c>, #<d>
- Or: "No safe parallel split right now"
**Next Step**
- Start with `$github-issue-start #<n>` if the user wants to implement the top recommendation.
Keep the report concise, but include enough reasoning that the recommendation is auditable.
Guardrails
- Do not create worktrees, branches, commits, pull requests, or issue comments.
- Do not edit repository files.
- Do not close, label, assign, or otherwise mutate GitHub issues.
- Do not assume cross-repository work.
- Do not force unrelated issues into a parallel plan just because multiple issues are open.
- If GitHub authentication or network access blocks issue reads, report the blocker and stop.
- If product intent is unclear after reading local docs and issue bodies, ask a focused question before ranking.