Refinement

---
name: refinement
description: Prepare technical analysis for backlog refinement meetings.
argument-hint: "<ticket-ids...> [--jql <query>] [--output <dir>] [--explore <depth>]"
disable-model-invocation: true
---

Prepare technical analysis for backlog refinement meetings.

## Arguments

`$ARGUMENTS`

- List of Jira ticket IDs: `/refinement BIL-3606 BIL-3580 BIL-3252`
- Output directory: `/refinement BIL-3606 --output ./refinement-2026-01-17/`
- Exploration depth: `/refinement BIL-3606 --explore thorough` (quick|medium|thorough)

## Step 1: Fetch Tickets

Ask the user to supply the ticket details:

> "I don't have direct Jira access. Please provide ticket details in one of these formats:
>
> 1. Jira REST API JSON (paste from `<your-jira-base>/rest/api/2/issue/TICKET-ID`)
> 2. Copy/paste the ticket description from Jira
> 3. Tell me the ticket IDs and I'll ask for details on each"

## Step 2: Explore Codebase

For each ticket, launch an Explore agent to find relevant code:

```
Task(subagent_type="Explore", prompt="""
Find code related to: {ticket.summary}

Context from ticket:
{ticket.description}

Search for:
1. Related components, models, APIs
2. Similar existing implementations
3. Test files
4. Migration patterns (if data changes needed)

Return:
- Key files with line numbers
- Existing patterns to follow
- Potential complexity factors
""")
```

Run up to 3 Explore agents in parallel for efficiency.

## Step 3: Analyze & Estimate

For each ticket, determine:

**Story Points (Fibonacci: 1, 2, 3, 5, 8, 13):**

| Factor           | 1-2 pts            | 3-5 pts          | 8-13 pts                 |
| ---------------- | ------------------ | ---------------- | ------------------------ |
| Files touched    | 1-2                | 3-5              | 6+                       |
| Backend changes  | None               | Model or API     | Model + API + Migration  |
| Frontend changes | None               | Single component | Multiple components      |
| New patterns     | Following existing | Minor adaptation | New architecture         |
| Dependencies     | None               | 1-2 tickets      | Blocked or complex chain |

**Generate for each ticket:**

1. Implementation steps (bullet points)
2. Key files to modify
3. Clarifying questions
4. Risk assessment

## Step 4: Generate Output

Create output directory structure:

```
{output_dir}/
├── README.md                     # Index with summary table
├── BIL-XXXX_{title_snake_case}.md  # Individual ticket files
└── ...
```

**Individual Ticket File Template:**

```markdown
# {ticket.key}: {ticket.summary}

**Story Points:** {estimated_points}
**Priority:** {ticket.priority}
**Status:** {ticket.status}

**Description:** {ticket.description | summarized}

---

## Key Files

| File              | Purpose       | Lines |
| ----------------- | ------------- | ----- |
| `path/to/file.py` | Model changes | 50-75 |
| ...               | ...           | ...   |

---

## Implementation Steps

1. Step one
2. Step two
3. ...

---

## Clarifying Questions

- Question 1?
- Question 2?

---

## Risk Assessment

**Risk Level:** Low | Medium | High

**Primary Risk:** Description

**Mitigation:** How to address
```

**Index File (README.md) Template:**

```markdown
# Backlog Refinement - {date}

## Summary Table

| Ticket   | Title | Points | Complexity   | Risk         | Details                     |
| -------- | ----- | ------ | ------------ | ------------ | --------------------------- |
| BIL-XXXX | Title | **N**  | Low/Med/High | Low/Med/High | [View](./BIL-XXXX_title.md) |

---

## Dependencies

{dependency_diagram}

---

## Action Items

- [ ] Action item from refinement
```

## Step 5: Present Summary

After generating files, present:

1. **Summary table** of all tickets with estimates
2. **Key risks** across all tickets
3. **Dependencies** between tickets
4. **Recommended discussion order** for refinement meeting

Ask:

> "I've created refinement documents in `{output_dir}/`. Would you like me to:
>
> 1. Add meeting notes after your refinement session?
> 2. Create any additional analysis?"

**Final output:**

> "Refinement analysis complete:
>
> - Local files: `{output_dir}/`
>
> Total: {n} tickets, {total_points} story points estimated"

## Guidelines

- Default output directory: `./refinement/` in project root
- Use architecture patterns from CLAUDE.md when exploring (if available)
- Keep estimates conservative - round up when uncertain
- Flag blockers and dependencies prominently
- If ticket description is vague, generate more clarifying questions
- Cross-reference related tickets if they appear in the batch