box-box/.agents/skills/groom/SKILL.md

name, description, argument-hint

name	description	argument-hint
groom	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.	<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–6 bullets and 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.