# Backlog Grooming

How to review and improve existing issues.

## Grooming Checklist

For each issue, verify:

### 1. Title Clarity
- [ ] Starts with action verb
- [ ] Specific and descriptive
- [ ] Understandable without reading description

### 2. Description Quality
- [ ] Has clear summary
- [ ] Explains the "why"
- [ ] Provides enough context

### 3. Acceptance Criteria
- [ ] Criteria exist
- [ ] Each criterion is testable
- [ ] Criteria are specific (not vague)
- [ ] Complete set (nothing missing)

### 4. Scope
- [ ] Not too broad (can complete in reasonable time)
- [ ] Not too narrow (meaningful unit of work)
- [ ] Clear boundaries (what's included/excluded)

### 5. Dependencies
- [ ] Dependencies identified
- [ ] No circular dependencies
- [ ] Blocking issues are tracked

### 6. Labels
- [ ] Type label (bug/feature/etc)
- [ ] Priority if applicable
- [ ] Component labels if applicable

## Common Issues to Fix

### Vague Titles
- Bad: "Fix bug"
- Good: "Fix login form validation on empty email"

### Missing Acceptance Criteria
Add specific, testable criteria based on the description.

### Scope Creep
If issue covers multiple features, split into separate issues.

### Stale Issues
- Close if no longer relevant
- Update if context has changed
- Add "needs-triage" label if unclear

### Duplicate Issues
- Close duplicate with reference to original
- Merge relevant details into original

## Grooming Workflow

1. **Fetch open issues**: `fj issue search -s open`
2. **Review each issue** against checklist
3. **Improve or flag** issues that need work
4. **Update issue** with improvements: `fj issue edit <n> --body "..."`
5. **Add labels** as needed: `fj issue label add <n> <label>`

## Questions to Ask

When grooming, consider:
- "Could a developer start work on this today?"
- "How will we know when this is done?"
- "Is the scope clear?"
- "Are dependencies explicit?"

## Batch Grooming

When grooming multiple issues:
1. List all open issues
2. Categorize by quality (ready, needs-work, stale)
3. Focus on "needs-work" issues
4. Present summary of changes made