triage

name	triage
description	Pick the next GitHub issue to work on. Reads PRD/roadmap, assesses project phase (early vs. mature), recommends one concrete starting point.

Triage GitHub Issues

Decide what's worth doing next based on project phase + issue priority, recommend a single concrete starting point, then implement on the current branch.

Don't favor bugs by default. Whether to recommend a feature or a bug depends on where the project is in its lifecycle. An early-stage project missing core MVP features should usually push features forward; a mature project with users should usually fix meaningful bugs first. Make this judgment yourself from the available evidence — don't ask the user to declare the phase.

Don't create a worktree. Work on the current branch unless the user explicitly asks for a worktree (e.g., "use a worktree", "wtree this"). Never set one up as a default step.

Input

The user may pass a GitHub URL as an argument. Supported formats:

URL pattern	What to fetch
github.com/owner/repo/milestone/N	Issues in milestone N
github.com/owner/repo/issues?labels=X	Issues matching label filter
github.com/owner/repo/issues?q=...	Issues matching search query
github.com/owner/repo/issues	All open issues
github.com/owner/repo	All open issues
github.com/orgs/owner/projects/N	Items from project board N

If no URL is provided, default to the current working directory's GitHub remote:

• Run gh repo view --json nameWithOwner -q .nameWithOwner to get owner/repo
• Also check ~/.claude/followups/<project>.md — items logged there from prior sessions are additional candidates alongside GitHub issues
• If that fails (not a repo, or no GitHub remote), fall back to docs-only signals if docs/PRD.md or docs/roadmap.md exist
• If neither a repo nor docs exist, stop and tell the user there's nothing to triage

Procedure

1. Determine the target repo and filters

If no argument was passed, detect the current repo:

• Run gh repo view --json nameWithOwner -q .nameWithOwner
• If that fails, check for docs/PRD.md / docs/roadmap.md — if present, you can still recommend roadmap work even without an issue tracker
• Default to fetching all open issues (no milestone/label filter)

If a URL was passed, parse it:

• Strip https:// prefix if present
• Split the path to get owner/repo
• Detect the URL type from the path and query string
• For milestone URLs, extract the milestone number
• For filtered URLs, parse query params (labels, q, milestone, assignee)

2. Fetch issues and read project docs

Issues — build and run the appropriate gh command:

• Milestone: gh issue list --repo owner/repo --milestone <N> --state open --json number,title,labels,body,createdAt,comments,assignees --limit 100
• Label filter: gh issue list --repo owner/repo --label <label> --state open --json number,title,labels,body,createdAt,comments,assignees --limit 100
• Search query: gh issue list --repo owner/repo --search "<query>" --json number,title,labels,body,createdAt,comments,assignees --limit 100
• All open: gh issue list --repo owner/repo --state open --json number,title,labels,body,createdAt,comments,assignees --limit 100
• Project board: gh project item-list <N> --owner <owner> --format json --limit 100

If the command fails (auth error, repo not found), report the error and stop.

Docs — if working in a local repo, also read whichever of these exist:

• docs/PRD.md — product spec; tells you what the project is supposed to be
• docs/roadmap.md — Now / Next / Later / Deferred sections; tells you where the project is heading and what's actively in flight

If neither docs nor issues are available, stop. If only one is available, use it alone. If both are available, use both as inputs to phase detection.

3. Assess project phase

Phase determines how much weight to give features vs. bugs. There are three buckets:

• early — MVP not done, core features missing, project hasn't shipped its first usable version
• mature — MVP shipped, has users (real or anticipated), incremental work dominates
• unclear — not enough signal to tell, or signals are balanced

Roadmap is the strongest signal when present. Read docs/roadmap.md:

• "Now" section lists core/foundational features (auth, primary data flow, key user-facing flows that aren't built yet) → early
• "Now" is small or empty, and "Next/Later" is mostly polish, refactors, integrations, or incremental enhancements → mature
• PRD references explicit phase numbers, milestones, or "MVP" framing — read those literally

Issue-tracker fallbacks (when roadmap is absent or thin):

• High ratio of open enhancement / feature issues to open bug issues, especially when features describe foundational capability → early
• Repo has tags/releases beyond v0.x, mature CI, and bug-heavy issue mix → mature
• Recently created repo (< 90 days, few commits) with feature-heavy issue list → early

When signals conflict: prefer the roadmap. The issue tracker reflects what's been filed, the roadmap reflects what's been planned. Note the conflict in your final summary so the user can correct you.

If you genuinely can't tell, set phase to unclear and apply no tilt.

4. Group related issues

Apply these heuristics in order to cluster issues:

Label clusters — Find issues that share the same area/component labels (ignore generic labels like bug, enhancement, good-first-issue). Group issues with 2+ shared specific labels.

Title prefixes — Look for common prefixes before :, —, or - in titles (e.g., "Dashboard: fix X" and "Dashboard: add Y" both belong to the "Dashboard" group).

Cross-references — Scan issue bodies for #N mentions. If issue A references issue B and both are in the set, group them together.

Merge overlapping groups — If two groups share 50%+ of their issues, merge them.

Ungrouped — Issues that don't cluster into any group are kept individually for the ranking step.

5. Score issues and rank groups

Per-issue score — type-agnostic. No bonus for being a bug or a feature.

Signal	Points
priority:critical label	+3
priority:high label	+2
priority:medium label	+1
Age > 30 days	+1
Active discussion (>3 comments)	+1
Referenced in docs/roadmap.md "Now" section	+2
Referenced in docs/roadmap.md "Next" section	+1
good-first-issue label	-1

Group score = sum of member issue scores.

Phase tilt at group ranking — applied after raw scores, before sorting:

Phase	Group composition	Multiplier
early	majority-feature group (≥50% feature/enhancement issues)	× 1.3
mature	majority-bug group (≥50% bug issues)	× 1.3
unclear	any	× 1.0

Critical/high-priority issues still float on raw score — the tilt nudges the long tail, it doesn't bury urgent items. A group containing any priority:critical issue should be ranked at least as high as the top-tilted group.

Sort groups descending by tilted score. Ungrouped issues are ranked alongside groups using the same scoring (just with a group of one).

6. Pick a single recommendation

Lead with one concrete starting point. Pick the top-ranked group, then decide the scope within that group:

• Bug groups — recommend tackling 2–3 issues max in one session, even if the group is larger. Err on the side of fewer. Only recommend more if every issue is genuinely trivial (one-line fixes, doc tweaks).
• Feature groups — recommend one feature unless the issues are tightly coupled (share 3+ labels and cross-reference each other) and obviously one piece of work split across tickets.
• Big single issue — if the top issue is large enough on its own to fill the session, recommend just that one.

Surface up to two also-worth-attention items below the recommendation: the next-highest group, and any priority:critical items the tilt may have pushed below the top pick.

7. Present the recommendation

Show a tight summary leading with one recommendation:

## Triage: owner/repo (N open issues)

Phase: <early | mature | unclear>
Signal: <one-line evidence — roadmap section, ratio, etc.>

### Recommendation
<Group name or issue title> — <issue numbers + titles>
Scope: <e.g., "1 feature", "3 small bugs", "~2 hours">
Why: <one sentence — fits phase, top score, etc.>

### Also worth attention
- <next group/issue> — <reason>
- <critical bug if not in top pick> — <reason>

Start on the recommendation? (or name another group/issue)

Wait for the user to confirm or pick something else.

8. Implement

• Read the chosen issue(s) in full: gh issue view <N> for each
• Explore the relevant areas of the codebase
• If the chosen scope has 4+ issues or the scope estimate exceeds 4 hours, ask the user if they want a plan drafted first (write to ~/.claude/plans/)
• Otherwise, start implementing directly

When working on a group, mention all related issue numbers in commit messages (e.g., "Relates to #12, #15, #18") so the PR links them.

Rules

• Don't favor bugs over features by default — let phase decide the tilt
• Don't create worktrees unless the user explicitly requests one; if they do, use wtree add <number> — never run git worktree manually
• Never commit automatically — ask before committing
• If the repo is not checked out locally, stop and tell the user
• If gh auth fails, suggest the user run gh auth login
• Don't attempt to implement a whole milestone — pick a focused subset; err on the side of smaller scope per session
• If the roadmap and issues conflict on phase signal, prefer the roadmap and note the conflict so the user can correct you