Groom

/groom

Strategic backlog management. Parallel investigation, synthesis, themed recommendations.

Modes

Backlog Format: backlog.d/

backlog.d/
├── 001-fix-auth-rotation.md
├── 002-add-webhook-retry.md
└── _done/
    └── 000-initial-scaffold.md

Each file:

# Fix auth token rotation

Priority: high
Status: ready | blocked | in-progress | done
Estimate: S | M | L | XL

## Goal
<1 sentence — what outcome, not what mechanism>

## Non-Goals
- <what NOT to do>

## Oracle
- [ ] <mechanically verifiable criterion — prefer executable commands over prose>
- [ ] <"How will we know this is done?" — even rough oracles make items buildable>

## Notes
<context, constraints, prior art>

Context Loading (all modes except tidy)

Before investigation, the orchestrator gathers baseline context:

1. Read project.md if it exists — store as project context for investigator prompts
2. Read backlog.d/ — note existing items, their status, and any gaps
3. Read .groom/retro/ if it exists — extract effort calibration and blocker patterns
4. Cap check: if >30 backlog items open, declare a reduction session (no new items until under cap)
5. Ask the user: "Anything on your mind? Bugs, friction, missing features?"

This takes <2 minutes. Do not block on missing artifacts — note their absence and proceed.

Investigation Bench

Three named investigators per mode, all launched in parallel via the Agent tool in a single message. See references/investigation-bench.md for full prompt templates.

MANDATORY PARALLEL FANOUT. All three investigators must launch simultaneously. A grooming session that only runs one investigator has failed the investigation goal.

Explore Investigators

For moonshot mode: the Strategist gets a modified prompt — "Forget the current backlog. What's the single highest-leverage thing we're not building?"

Rethink Investigators

Investigator Output Format (shared)

Every investigator returns this exact shape:

## [Name] Report
### Top 3 Findings
1. [finding] — Evidence: [file:line / commit / metric]. Impact: high/med/low.
2. ...
3. ...
### Strategic Theme
[One sentence: the overarching theme these findings point to]
### Single Recommendation
[One concrete action. Not a list. Not "consider." A specific thing to do.]

Synthesis Protocol

After all investigators return, the orchestrator (you) synthesizes. Do NOT present raw findings. Do NOT delegate synthesis to a sub-agent — this requires product judgment.

1. Cross-reference — Which findings appear across 2+ investigators? (highest signal)
2. Theme extraction — Group findings into 2-4 strategic themes. A theme is a cluster of findings that share a root cause or a shared solution. Not individual items — themes.
3. Dependency map — Do any themes depend on others? (e.g., "test infrastructure" enables "safe refactoring")
4. Rank — Order by: (impact on product vision) × (feasibility) / (effort)
5. Present — One theme at a time. For each: evidence from investigators, recommended action, rough effort (S/M/L). Ask the user: explore deeper, write backlog item, or skip?

Output format:

## Grooming Synthesis

### Investigator Convergence
[Findings that appeared from 2+ investigators — these are highest signal]

### Theme 1: [Name]
**Evidence:** Archaeologist found X, Strategist found Y, Velocity confirms Z.
**Recommendation:** [one concrete action]
**Effort:** S/M/L
**Impact:** [why this matters for the product vision]

### Theme 2: ...

### Dependency Order
Theme A enables Theme B. Recommend executing A first.

Workflow: Explore

Phase-gated. Each phase must complete before the next begins.

1. CONTEXT — Load baseline (see Context Loading above)

2. INVESTIGATE — Launch all three explore investigators in parallel

Gate: all three returned structured reports.

3. SYNTHESIZE — Cross-reference, theme, rank (see Synthesis Protocol)

Gate: themes extracted with evidence and recommendations. Not raw findings.

4. DISCUSS — Present one theme at a time. Recommend, don't list.

Gate: user decides per theme (explore deeper / write item / skip).

5. WRITE — Create backlog.d/ files for approved themes

Gate: every item has Goal + Non-Goals + Oracle. Use references/agent-issue-writing.md for issue quality standards.

6. PRIORITIZE — Reorder backlog.d/ by value/effort ratio

Workflow: Rethink

1. CONTEXT — Load baseline + user specifies the target system

2. INVESTIGATE — Launch all three rethink investigators in parallel

Gate: all three returned structured reports.

3. SYNTHESIZE — Distill into 2-3 architectural options with honest tradeoffs

Always include "do nothing" as a viable option.

4. RECOMMEND — Pick one option. Argue for it. Be opinionated.

Gate: one clear recommendation with reasoning.

5. DISCUSS — User approves, modifies, or rejects

6. WRITE — One backlog.d/ item for the recommended change

Workflow: Scaffold

Bootstrap a new project with quality gates:

1. Test infrastructure (framework, coverage gates)
2. Linting (ESLint/Biome/clippy with strict rules)
3. Type checking
4. Pre-commit hooks
5. CI pipeline
6. CLAUDE.md with project-specific instructions

Workflow: Tidy

1. Backlog audit — count open items, check against 30-item cap
2. Archive completed items to backlog.d/_done/
3. Delete stale items (>30 days untouched, no longer relevant)
4. Verify each remaining item has Goal + Oracle
5. Reorder remaining by priority
6. If BACKLOG.md / icebox exists, review it — promote, archive, or leave

Gotchas

• Investigators returning "everything is fine" — Red flag. Push harder. Every codebase has findings; an investigator that found none didn't look.
• Synthesis that lists findings without theming — That's a report, not synthesis. Group into themes before presenting.
• Themes without recommendations — That's a menu, not grooming. Pick one action per theme and argue for it.
• Running one investigator and calling it done — Mandatory parallel fanout. All three, every time.
• Items without oracles — If you can't write a "definition of done" with checkable criteria, the item isn't scoped. Go back and scope it.
• Over-decomposing — An agent-hour of work is one item, not three. Compression ratios make most splits unnecessary.
• Backlog as graveyard — Items >30 days old with no progress are dead. Archive or delete during tidy.

Principles

• Investigate before opining — parallel investigation first, opinions after evidence
• Theme, don't itemize — strategic themes, not feature laundry lists
• Recommend, don't list — always have an opinion, argue for it
• One theme at a time — don't overwhelm during discussion
• Product vision is the ranking function — rank by impact on the user, not technical elegance
• Every item needs an oracle — if you can't verify done, the item isn't ready
• File-driven — backlog.d/ is the source of truth