groom

name	groom
description	Always-on backlog grooming. Tidy, brainstorm, interrogate, investigate, research, and simplify in a single loop. Tidy is not a mode — it happens every time. Strategic-layer work is a mega-sweep: swarm investigation, external research, critique, synthesis, and backlog shaping across product, codebase, docs, infrastructure, ops, architecture, system design, value prop, and agent readiness. Use when: "groom", "what should we build", "rethink this", "biggest opportunity", "backlog", "prioritize", "backlog session", "audit skills", "skill quality audit". Trigger: /groom, /groom audit, /backlog, /rethink, /moonshot, /scaffold.
argument-hint	[audit|--emphasis explore|rethink|moonshot|scaffold] [context]

/groom

Keep backlog.d/ true and make the project more ambitious. Normal strategic /groom is a mega-sweep, not triage: boil the ocean on purpose, then distill it into a world-class plan and backlog diff. A groom that only lists, lightly prioritizes, or emits a tiny handful of issues is incomplete unless the user explicitly scoped the run down.

The backlog diff is the artifact. Prose exists to justify it. Groom is a conversation at the seams where the operator's judgment is the scarce input. At intake, interrogate the operator on ambition, vision deltas, and hidden priors so the sweep aims true — the grill-me-style posture in primitives/shared/references/interrogate-first.md is the default here, not a fallback gated on whether they arrived with a backlog item. The investigation sweep itself stays autonomous — explore the codebase for what it can answer; reserve interrogation for the operator's judgment, not for facts you can read.

julius-caveman for interim synthesis only; findings, code, commits, and final artifacts stay normal English.

Project Vision

Every strategic groom creates, refreshes, or explicitly validates a durable project vision before ranking work; without one, brainstorming and backlog movement collapse into local cleanup.

Read root VISION.md when present; if missing or stale, route to /vision (shared AGENTS.md: Vision). Groom's delta: it drafts the smallest durable vision artifact itself when none exists — prefer root VISION.md; docs/product.md, a roadmap doc, or a named backlog epic only when repo evidence says root vision is the wrong fit — and treats that draft as a first-class groom emission rather than waiting on a separate /vision pass.

• Keep the vision concrete: audience, job-to-be-done, category, standards, non-goals, strategic bets, and what excellent looks like in 6-12 months.
• Revise the vision when live evidence contradicts it; don't bury direction changes in chat, issue comments, or the final report only.
• Backchain: themes and tickets should say which part of the vision they advance, de-risk, simplify, or deliberately reject.
• A vision or moonshot artifact can carry a one-glance system map when relationships or sequencing are too complex for prose alone: primitives/shared/references/image-generation.md.

Tidy (mandatory, mechanical)

Tooling owns closure; consume it, don't hand-roll it:

default="$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')"
cargo run --locked -p harness-kit-checks -- backlog ids-from-range "origin/${default:-main}..${default:-main}"
cargo run --locked -p harness-kit-checks -- backlog archive "$id"   # idempotent

• Archive every ticket closed by Closes-backlog:/Ships-backlog: trailers or marked done/shipped in frontmatter. Commit as chore(backlog): archive shipped tickets swept by /groom.
• Flag stale in-progress (merged/deleted branch, or 30+ days untouched).
• Surface duplicates with a proposed consolidation — never merge silently.
• Backlog size is telemetry, not policy. If the active queue looks too broad, report the evidence: count, age, duplicates, stale owners, orphaned themes, and unfocused small items. Consolidate only when tickets genuinely share one outcome. Never veto an evidenced emission because of an arbitrary item count.

Trailer canon lives in meta/CONTRACTS.md. Emit trailers only via git interpret-trailers; hand-formatted variants are invisible to tooling.

Delegation

Delegate per the shared Roster contract (shared AGENTS.md: Roster). Strategic grooming is high-stakes by declaration and defaults to the swarm: independent lanes for product/value, operator experience, runtime reliability, architecture, simplification/deletion, security/privacy, docs/onboarding, ops/infra, testing/verification, agent readiness, and external exemplars, with the lead keeping final prioritization. Routine grooming — a tidy-only pass, a scoped ticket check — scales the bench down to the stakes per the Roster contract instead of running the full swarm.

Mega Sweep

For any strategic groom, load references/mega-groom.md. It is the contract for swarm size, coverage map, source matrix, output shape, and the "world-class plan" bar. Use references/investigation-bench.md only for lane prompt shapes; it is a template library, not the whole run.

Ambition Floor

Calibrate scope to what frontier agents can execute, not what a human team can staff. Execution is cheap; vision is the scarce input. Strategic grooming must describe the best version of the whole project, then backchain from that standard into epics, deletions, sequencing, and first pickups.

• Brainstorm deep, from perspectives composed for this repo. There is no canonical list of layers to sweep. Pick the obvious axes this codebase demands, then add lenses no stock list would hand you — invert a premise, borrow from an adjacent domain, ask what a competitor, operator, or first-time user would notice. Fan the perspectives out as parallel fresh-context lanes; pull in /research when outside knowledge would change a verdict. When the sweep keeps returning the obvious (the mundane harvest failure), route the divergence through nous-creative-ideation — a routed library of named methods (lateral provocations, analogy/biomimicry, premortem-and-inversion) that manufactures non-obvious lenses on purpose. The bar is genuine diversity and depth of exploration, judged fresh each session.
• Describe the best version of this software, not the next safe increment: elegant, easy to change, personalizable, delightful, operationally boring, and valuable enough to matter. The distance between that vision and the live repo is backlog material; close it with epics.
• Epic-scoped by default. Strategic emissions are epics — a product outcome with an ordered child sequence — never pre-shredded tasks. Small items exist as children of an epic or as genuine isolated fixes.
• Ambition is not slop. Every epic's premise survives the same vetting as any finding: open the file, run the command. A perspective that comes back with "all fine here" is making a claim — vet it like one. The floor raises scope, not tolerance for unevidenced claims.

Judgment (the actual grooming)

Investigate before opining. A tidy-only pass exists, but only when the user asks for one; any other session owes the references/mega-groom.md sweep, with genuinely independent perspectives run in parallel and /research when outside context would change a verdict. Fresh-context lanes exist to decorrelate judgment, not to fill a roster.

• Read the live code, not just ticket text. Hotspots, debt concentrations, the oldest stuck ticket. Every codebase has findings; "everything is fine" means the investigation was shallow.
• Challenge premises of the top items. Symptom or root cause? A ticket's framing is a first draft. Reframe before re-ranking.
• Propose deletions. The best groom shrinks the backlog. Every deletion is a proposal with rationale — humans ratify removals.
• Audit the repo's own harness. Agent readiness is backlog work, not a separate ceremony: does this repo have a verification skill with its real routes/commands (the highest-impact skill category)? Verified build/test/ lint commands and conventions an agent can discover cold? Runbooks for its deployed surfaces? A CI gate that would catch the likely failure? A meaningful, enforced quality floor that gates the diff and ratchets legacy debt, or only advisory, arbitrary gates (primitives/shared/references/quality-gates.md)? Security gates that catch secret leaks in files and Git/PR metadata before publication? Stale AGENTS/CLAUDE prose? Product context a cold agent would need? Each gap is a ticket like any other.
• Vet findings before presenting them. Re-check each claim against the live repo — open the file, run the command. A plausible finding that doesn't survive a second look is noise that erodes trust in the whole groom.
• Theme, then recommend. Group findings by shared root cause, rank by impact discounted by confidence — effort barely discounts now that agents execute — and argue for one concrete action per theme. Synthesis stays on the lead; when the plan is contestable, land it with the operator the same grill-me way — walk the decision tree (sequencing, deletions, the next pickup) one branch at a time, recommending each — instead of dropping the full plan for a rubber-stamp.

Ticket Format

backlog.d/<nnn>-<kebab-slug>.md with Goal + Oracle always, plus a Verification System for M+/ready work — full template, epic shape, and promotion rules: references/ticket-format.md.

Audit Mode

/groom audit is a read-only harness-health report, not a grooming run:

cargo run --locked -p harness-kit-checks -- telemetry --repo .

It summarizes skill/prompt usage from hook logs (and staleness vs last edit). Read it with judgment: low usage with high value-when-used is fine — say so; low usage with no story is a deletion candidate. Present findings ordered by severity; do not auto-fix.

Refuse

• Never auto-delete or silently merge tickets.
• Never archive a ticket whose trailer points at an unmerged branch.
• Never let backlog size alone veto an evidenced ticket or epic.
• Never skip the swarm on a strategic/mega-sweep groom when subagent, peer CLI, or sprite lanes are available — it's high-stakes by declaration; if all delegation is blocked, report degraded mode and do the local matrix. Routine grooming may scale the bench down per the Roster contract.

Gotchas

• Menu, not grooming. Themes without a defended recommendation are a report. Pick one action per theme and argue it.
• Mundane harvest. A strategic session that only finds small, safe work is not done. Widen the swarm, add external research, invert the premise, and inspect neglected surfaces before concluding the repo has no ambitious, evidence-backed moves.
• Stock-lens grooming. Running the same investigator roster in every repo is process, not thought. The revealing perspectives are the ones composed for this codebase, this session.
• Over-decomposing. An agent-hour of work is one ticket, not three; a coherent multi-ticket ambition is one epic, not ten orphan tasks.
• Backlog as graveyard. Age is a stale signal, not an automatic verdict. Inspect branch, owner, and live relevance before flipping, archiving, or proposing deletion.
• Accepting the ticket's framing. Five-whys the top items before re-ranking them.

Completion Gate

See primitives/shared/AGENTS.md (Completion Evidence, Closeout) for the shared core; this phase adds:

1. Tidy diff — archived, flipped, flagged; by ID, no padding.
2. Source matrix — swarm lanes, local commands, external research, skipped/failed lanes, and what each contributed.
3. World-class plan — vision, gaps, themes, sequencing, deletion/ consolidation candidates, and the one best next pickup.
4. Emissions — epic/ticket edits with **Why:** naming the evidence lane; strategic emissions show breadth across the domain map, not just the easiest implementation slice.
5. Residual — open questions, blocked dependencies, unverified areas, and what would make the sweep stronger.

/groom audit scores skill quality separately (see Audit Mode above); backlog mechanics are enforced by harness-kit-checks backlog subcommands. Apply non-destructive backlog edits when the user asked for grooming; deletions, abandonments, and silent merges stay proposals unless explicitly approved. A groom run ends with a clean tree: archives committed, emissions written, deletions awaiting ratification.