with one click
with one click
| name | groom |
| description | Groom GitHub issues from needs-details to ready |
This command helps transform draft issues (labeled needs-details) into implementation-ready issues (labeled ready).
Current issues needing grooming:
!gh issue list --label needs-details --json number,title --limit 10 2>/dev/null || echo "Could not fetch issues"
Draft issues (.github/ISSUE_TEMPLATE/draft.yml):
needs-detailsReady issues (.github/ISSUE_TEMPLATE/task.yml):
Issue number: $ARGUMENTS
If an issue number was provided above (not empty):
If no issue number was provided:
Fetch issues with needs-details label:
gh issue list --label needs-details --json number,title,labels,milestone --limit 20
If no issues found, inform the user and exit.
Ask the user to select a mode:
For Single mode:
For Preview & Pick mode:
Analyze all issues considering:
Present a ranked list to the user showing:
PRIORITY RANKING:
1. #42 - User authentication flow
Priority: HIGH | Reason: Blocks #43, #44; milestone: MVP
2. #38 - File upload validation
Priority: HIGH | Reason: Security-critical; no dependencies
3. #35 - Dashboard layout
Priority: MEDIUM | Reason: User-facing; straightforward scope
... (show all issues with rankings)
Present the ranked list and ask the user to select which issues to groom:
Proceed to Multiple mode with selected issues
For Multiple/Auto-select mode:
subagent_type: "groom-research" — make all Task calls in the same message so they run concurrently. Do NOT use run_in_background.This is a TWO-PHASE process. Do NOT skip the first phase.
Fetch issue details:
gh issue view <number> --json number,title,body,labels
Research codebase context by spawning a Task with subagent_type: "groom-research" (do NOT use run_in_background). Pass it the issue number and details. The agent will return structured research findings.
Identify decisions and alternatives:
Ask the user for input on findings:
Example questions to surface:
Only proceed here AFTER getting user input on key decisions.
Draft improved body incorporating user decisions:
## Description
[Expanded description based on research AND user decisions]
## Acceptance Criteria
- [ ] [Specific, testable criterion reflecting agreed approach]
- [ ] [More criteria based on user input]
## Out of Scope
- [Items explicitly excluded based on user decision]
- [Scope boundaries the user confirmed]
Present draft to user:
If approved, update the issue:
gh issue edit <number> --body "<new body>"
gh issue edit <number> --remove-label needs-details --add-label ready
After all issues are processed, provide a summary:
When subagents return their research:
Before presenting drafts to the user, review them for quality and codebase alignment using parallel subagents.
Spawn three review agents in the same message (do NOT use run_in_background — make all three Task calls in one message so they run concurrently and return results directly). Use model: "opus" for all review agents — do not let them default to haiku:
Issue Quality Review (subagent_type: "general-purpose"):
.claude/skills/groom/templates/review-criteria.mdCodebase Alignment Review (subagent_type: "general-purpose"):
Related Issues Review (subagent_type: "general-purpose"):
gh issue list --state open --json number,title,body,labels --limit 50Collect results from all three agents (each Task's return value contains the agent's final structured output directly)
Process findings:
Proceed to Final Review with any flagged concerns
Fix directly:
Flag for user discussion:
After all drafts are ready, you MUST review each issue individually with the user.
Present all drafts with a summary showing each issue's title and key changes
Ask the user about each issue. Each question should have these options (in this order):
ai-drafted for later human reviewneeds-details for nowApply updates based on responses:
--remove-label needs-details --add-label ready--remove-label needs-details --add-label ready --add-label ai-draftedneeds-detailsHandle "Request changes" responses:
| Label | Meaning |
|---|---|
needs-details | Draft issue, not ready for implementation |
ready | Fully detailed, ready for implementation |
ai-drafted | Content generated/groomed by AI, pending human review |
Note: ai-drafted is used WITH ready - the issue is detailed enough to work on, but a human hasn't verified the AI's decisions yet.
Issues should have a priority label for triage and backlog prioritization:
| Label | Color | When to Use |
|---|---|---|
priority: critical | Red | Must be addressed immediately |
priority: high | Orange | Important, should be addressed soon |
priority: medium | Yellow | Normal priority |
priority: low | Green | Nice to have, address when time permits |
During grooming, suggest an appropriate priority label based on:
During grooming, you may identify work that should be separate issues (prerequisites, follow-ups, discovered scope). When creating these:
needs-details labelFor issue relationships (sub-issues, blocking): Read docs/ai/github-workflow.md for the GraphQL commands and decision guide on when to use parent/child vs blocking relationships.
docs/ai/github-workflow.md)[HINT] Download the complete skill directory including SKILL.md and all related files