Grooming Issues

Grooming Issues: capture the intent before anyone sizes or builds it

An issue can exist — a title, a paragraph, maybe a stakeholder's wish — long before it is buildable. Grooming is the pass that turns that into a story the team can trust: through questions to the engineering/project lead, it pins the intent, scope, and direction until the written issue faithfully reflects the ask, then writes that into the body in the six-section groomed shape. It captures the what and why. It deliberately does not decide the how or the cost — that is the technical-recon skill, which runs next.

The pipeline: a raw issue → grooming (this skill: intent to ≥90%, body groomed) → technical-recon (dev-side approach + LoE) → dispatch (per the orchestrating-slots and issue-locking skills). Grooming hands a clean story to recon; recon hands a sized, vetted issue to dispatch.

Compose with the siblings: the six-section anatomy and label taxonomy come from the issue-filing skill (gh-issue-filing / jira-issue-filing); the emoji-answerable clarification loop is the same one the technical-recon skill documents (reuse its comment format and template); when grooming completes, the technical-recon skill picks the issue up.

Project bindings

Define in the adopting project's CLAUDE.md; referred to by placeholder.

| Binding | Meaning | Example | |---|---|---| | ` | Label/status meaning "story is groomed, ready for technical recon" | a groomed label, or a Ready for Tech Review status | | | "questions are pending the lead's answers" | needs-spec-input | | | The heading that marks the acceptance-criteria block in the body | ## Acceptance criteria` |

Grooming reuses the issue-filing skill's body anatomy and the technical-recon skill's question channels; it adds no labels of its own beyond the two states above.

The one hard rule: do not touch existing acceptance criteria

If the issue already has acceptance criteria written, leave them exactly as they are — verbatim — unless the operator explicitly tells you to change them in this run. Existing AC is a contract that stakeholders may have negotiated and approved; an agent silently rewriting, tightening, or "improving" it changes the scope of work without anyone agreeing to the change. This has shipped the wrong thing in practice.

So:

• AC already present → preserve it byte-for-byte. If grooming surfaces that the AC looks wrong, incomplete, or contradicts the lead's stated intent, do not edit it — raise it as a question (**Decision needed: the current AC says X but you described Y — keep / replace / add?**) and let the lead decide. Only act on AC when the operator's answer authorizes it.
• No AC yet → you may draft acceptance criteria as part of grooming, but each item must be independently testable (issue-filing skill), and present the drafted AC for the lead's confirmation rather than treating it as settled.
• Operator says "rewrite the AC" (or similar explicit instruction this run) → then, and only then, edit it; record ac=operator-edited in the contract and note what changed in a comment.

Everything else in the body — title, symptom/context, desired behaviour, out-of-scope, open-questions-now-resolved, traceability hint — grooming may write and improve freely toward the issue-filing anatomy.

Reach ≥90% that the story reflects the ask

Read the issue and any linked context first, then ask the lead about whatever is undecided and material: the actual intent behind the request, scope boundaries (what's in, what's explicitly out), the definition of success, edge cases and error behaviour, affected users/surfaces, and any conflict between the existing text and what they describe. Ask until you are ≥90% confident the written story reflects what the lead actually wants — below that, ask; do not paper over ambiguity with plausible-sounding body text.

Questions go through the same two channels as the technical-recon skill, in priority order:

1. Interactive ask-question tool, if the run has one — multiple-choice with a recommended option and a write-in escape, looping until ≥90%, then write the body in the same pass.
2. No question tool (the usual fanned-out sub-agent case) — ask via emoji-answerable comments: one comment per question, each option tagged with a reaction emoji the lead clicks, a one-line legend at the bottom, kept within the tracker's reaction set (GitHub allows only 👍 👎 😄 🎉 😕 ❤️ 🚀 👀). Use the technical-recon skill's question-comment template verbatim. Then set `` and stop.

Rerun to continue (resume, not restart). When grooming stalls on posted questions, the lead reacts/answers and reruns the groom command. On rerun, read your prior questions and the lead's reactions/replies first, fold them in, and — if now ≥90% — write the groomed body and move to ``. Never re-ask an answered question; a written reply overrides a reaction.

The sandbox

Allowed: read the issue, its comments, and linked context (lightly read the repo only for the context needed to ask good questions — deep code tracing is recon's job, not grooming's); use the interactive ask-question tool if present; post emoji-answerable question comments; edit the issue body's non-AC sections toward the groomed anatomy; set ` / `.

Forbidden — stop and emit GROOM-ERROR: :

• Modify existing acceptance criteria without an explicit operator instruction this run (the hard rule above).
• Assert a technical approach or a level-of-effort — that is the technical-recon skill; grooming that pre-judges the build biases the estimate.
• Claim/assign the issue, write code, or open a PR.
• Mark the issue ready-to-dispatch — grooming earns ``, not dispatch-readiness; technical-recon earns that.

Verdict and handoff

| Verdict | When | State set | |---|---|---| | groomed | ≥90% on intent; body meets the six-section anatomy; existing AC preserved (or operator-authorized edits applied) | ` — the issue is ready for /gh-issue-recon or /jira-issue-recon | | **needs-spec-input** | Questions are pending the lead's answers, below the 90% bar | ` + the question comments; rerun to continue |

Output contract

Each grooming agent ends with exactly one line:

GROOM : verdict=groomed ac=
GROOM : verdict=needs-spec-input questions= (awaiting the lead's answers; rerun to continue)
GROOM-ERROR: 

Validate against what was actually written (gh issue view / getJiraIssue): the body changed, existing AC is byte-identical unless ac=operator-edited, and the state moved.

Anti-patterns

• Rewriting approved acceptance criteria because it "reads better" — the headline failure this skill exists to prevent.
• Grooming past a guess. Writing confident body text over an unresolved intent question is worse than a stalled issue with clear questions.
• Doing recon's job. Implementation approach and LoE belong to the technical-recon skill; grooming that asserts them biases the later estimate.
• Inventing scope. Out-of-scope and success criteria the lead never confirmed become accidental requirements once they are in the body.

Token discipline: caveman working, humanizer for the story

Grooming runs in the same high-volume loop as the sibling skills — operate in caveman mode (load the caveman skill) for working output (reasoning, the batch summary, status), keeping machine-precise content byte-exact (labels/fields, JQL, gh/MCP commands, the GROOM contract line, and any existing acceptance-criteria text — which is byte-exact by rule anyway).

But the body you write into the issue is the story a human reads and an implementer builds from — its prose (symptom/context, desired behaviour) is not caveman. Draft it naturally and run it through the humanizer skill before saving, so the groomed issue reads human-written. Leave existing AC, any file:line refs, and the contract line exactly as captured.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skyfox675
• Source: skyfox675/agents-skills
• License: MIT

Install and usage instructions live in the source repository linked above.