Card grooming

TradeMasterAPI uses GitHub issues as its backlog. As the issue count grows (epics, bugs, security findings, agent-proposed work), the backlog drifts into a mix of:

• Well-formed, ready-to-pick issues
• Vague notes that are really reminders-to-think
• Stale duplicates or obsolete items
• Huge multi-week things mis-filed as single issues

Manual grooming is dull. The card-groomer agent does it automatically.

When to run it

• Before sprint planning / picking the next thing to work on
• After a CI security run opens a burst of area:security findings
• When the needs-grooming pile gets long
• Not during active feature work; grooming can be noisy

How to run it

From inside Claude Code on this project:

Task card-groomer to review the open backlog.

Or to groom a single issue:

Task card-groomer to groom issue #84.

What it produces

For each issue it touches:

1. A structured comment scoring 5 axes (atomicity, goal, acceptance criteria, epic link, labels).
2. A label update — groomed (ready to pick up) or needs-grooming (explain why + suggested fixes).
3. For non-atomic issues, a suggested split posted as a comment. The agent does not actually split — that's a human decision.

At the end, the agent summarizes its pass in the session log: how many groomed, how many flagged, what needs human judgment.

What it will not do

• Close issues. Only humans close.
• Rewrite issue bodies. Only suggest edits in comments.
• Create new issues. Only propose splits.
• Label priority / severity by guessing. Only labels it can defend from the issue body.

Rubric in one line

Ready = atomic + clear goal + acceptance criteria + epic link + correct labels.

Anything less gets needs-grooming.

Tuning

The rubric and don'ts live in .claude/agents/card-groomer.md. Edit there if you want to change scoring, add new labels, or tighten guardrails. The agent reloads on each invocation so changes take effect immediately.