2026-07-03 23:18:31 -04:00
---
name: groom
2026-07-11 18:10:34 -04:00
description: 'Groom a box-box GitHub issue into a Ready spec via a seeded grill-me interrogation. Use when the user asks to groom an issue, for example "/groom <issue-number>" or "$groom <issue-number>" with optional "--lens architect". Single-issue path: asks targeted questions, writes a structured spec into the issue body, sets Effort/Priority, and leaves Stage at Research for approval.'
2026-07-03 23:18:31 -04:00
argument-hint: <issue-number> [--lens architect]
---
# /groom — refine one issue into a Ready spec
Groom issue * * $ARGUMENTS** on the box-box roadmap (Project #2 ): drive it from the
backlog into a fully-specified Ready ticket through a grill-me session.
## 0. Setup
- Parse the first token of the arguments as the **issue number ** . An optional
`--lens <name>` pulls in a lens overlay (currently: `architect` ).
- Run: `source .agents/lib/gh.sh && project_refresh` (fresh field/item state).
- Load context **before asking anything ** : `issue_json <n>` , read `CLAUDE.md` , and
explore the code paths the issue implicates.
- Move it into grooming if it isn't already there: `set_stage <n> Research` .
## 1. Grill
- Read `.agents/personas/grill.md` . If `--lens <name>` was given, also read
`.agents/personas/<name>.md` and apply it on top.
- Run the grill exactly per those rules: **one question at a time ** , recommendation
first, **hybrid ** asking (AskUserQuestion for discrete decisions with the
recommended option first and labelled "(Recommended)"; prose for open-ended), and
**explore the code to self-answer ** wherever possible — only ask about genuine forks.
- Track the resolved decisions as you go.
## 2. Synthesize
- When no open branches remain, summarize the shared design concept in 3–
confirm it with the user.
- Then invoke the **write-spec ** skill for issue `<n>` , handing it the resolved
decisions, so it renders `.agents/prompts/ready-spec.md` into the issue body and
sets Effort + Priority.
## 3. Hand back (human gate)
- Do **not ** auto-advance to Ready — that's the user's call. Report that the spec is
written, Stage is `Research` , and they should review the issue and flip Stage →
`Ready` when satisfied (`set_stage <n> Ready` ).
- Print the issue URL (`issue_url <n>` ).
Stay focused on THIS issue's design throughout. Note but don't chase out-of-scope ideas.
