---
name: backlog-groom
description: Groom backlog issues by writing clear acceptance criteria, clarifying descriptions, and ensuring issues are well-defined and ready for implementation.
argument-hint: "[issue number or 'review' to identify issues needing grooming]"
---

You are grooming the backlog for the **Prisme project** (`prisme` on PyPI) — a code generation framework that produces full-stack CRUD applications from Pydantic model specifications.

## Your Responsibility

Ensure backlog issues are **ready for implementation** by:
- **Writing clear acceptance criteria** (AC)
- **Clarifying vague descriptions**
- **Adding technical context** from dev docs/plans
- **Identifying missing information**
- **Linking related issues/PRs**

## Context Sources

```bash
# Open issues without clear AC (check body for "Acceptance Criteria" or "AC:")
gh issue list --state open --json number,title,body,labels

# Issues in Backlog or Up Next
gh project item-list 2 --owner Lasse-numerous --format json | jq '.items[] | select(.status == "Backlog" or .status == "Up Next")'

# Related plans and docs
ls dev/plans/*.md dev/issues/*.md
```

Read these files for context:
- `dev/roadmap.md` — feature priorities and scope
- `dev/plans/index.md` — implementation plans
- `dev/issues/index.md` — issue analysis documents
- Specific plan files from `dev/plans/` related to the issue

## What Makes a Well-Groomed Issue

A ready-for-implementation issue has:

1. **Clear title** — Actionable, specific (e.g., "Add email templates for password reset" not "Email stuff")
2. **Context** — Why this is needed, user value, current behavior
3. **Acceptance criteria** — Specific, testable outcomes (use "Given/When/Then" or checklist format)
4. **Technical notes** — Links to relevant code, architecture decisions, constraints
5. **Scope boundaries** — What's in scope, what's explicitly out of scope
6. **Dependencies** — What must be done first, what this unblocks

## Acceptance Criteria Format

Use one of these formats:

### Checklist Format (Preferred for features)
```markdown
## Acceptance Criteria

- [ ] User can upload a profile image from the profile page
- [ ] Uploaded images are validated (max 5MB, PNG/JPG only)
- [ ] Image is resized to 512x512 and stored in S3
- [ ] Profile page displays the uploaded image
- [ ] Users without an image see a default avatar
```

### Given/When/Then (Preferred for bugs)
```markdown
## Acceptance Criteria

**Given** I am a logged-in user
**When** I navigate to /profile and upload a valid image
**Then** the image appears in my profile within 5 seconds

**Given** I am a logged-in user
**When** I upload a 10MB file
**Then** I see an error message "File too large (max 5MB)"
```

## Grooming Process

For each issue:

1. **Read the issue** and any related dev docs/plans
2. **Identify gaps**:
   - Missing context or user value?
   - Vague or ambiguous requirements?
   - No acceptance criteria?
   - Unclear scope?
3. **Draft improvements**:
   - Add AC if missing
   - Clarify description
   - Add technical context
   - Link related issues/plans
4. **Update the issue body** after user confirmation

## Example Transformation

### Before (vague)
```markdown
**Title:** Add email support

We need email in the app.
```

### After (groomed)
```markdown
**Title:** Add transactional email templates for auth flows

## Context
Users need to receive emails for password reset, email verification, and account notifications. Currently, these flows are incomplete without email delivery.

## Acceptance Criteria

- [ ] SMTP configuration added to `StackSpec.email_config`
- [ ] Password reset email template with magic link
- [ ] Email verification template with confirmation link
- [ ] Welcome email sent on new account creation
- [ ] Email service integrated with FastAPI auth endpoints
- [ ] Templates support brand customization (logo, colors)
- [ ] Delivery failures logged and retried (max 3 attempts)

## Technical Notes
- Use `prisme.generators.email` (create if needed)
- Templates in `prisme/templates/jinja2/email/`
- SMTP config similar to `DatabaseConfig` pattern
- See `dev/plans/email-integration.md` for architecture

## Out of Scope
- Marketing/newsletter emails (future feature)
- Email analytics/tracking (future feature)

Related: #93 (email integration tracking issue)
```

## Output

For each groomed issue, provide:
- **Updated issue body** with AC and clarifications
- **Justification** for changes made
- **Flag any blockers** or dependencies discovered

## User Confirmation

**Always present the updated issue body** to the user before applying changes.

For single issues: Show the before/after diff and ask for approval.

For bulk grooming (>3 issues): Use **AskUserQuestion** to confirm before updating multiple issues.

Modifying issue descriptions affects team understanding and implementation scope, so user review is essential.
