---
title: "Refinement Notes"
description: "Documents backlog refinement session outcomes including stories refined, estimates, questions raised, and decisions made. Use during or after refinement to capture the results and share with absent team members."
generated: true
source: scripts/generate-skill-pages.py
tags:
  - Iterate
  - coordination
---

:::note[Quick facts]
**Phase:** Iterate | **Version:** 2.0.0 | **Category:** coordination | **License:** Apache-2.0
:::

**Try it:** `/refinement-notes "Your context here"`

Refinement notes capture the outcomes of backlog refinement (grooming) sessions.what was discussed, what was estimated, and what decisions were made. They serve as a quick reference for team members who missed the session and a historical record of how stories evolved from idea to ready-for-sprint.

## When to Use

- During refinement sessions to capture decisions in real-time
- After refinement to share outcomes with absent team members
- When onboarding new team members to explain backlog context
- Before sprint planning to review what's been refined
- When stories need re-refinement due to time elapsed

## How to Use

Use the `/refinement-notes` slash command:

```
/refinement-notes "Your context here"
```

Or reference the skill file directly: `skills/iterate-refinement-notes/SKILL.md`

## Instructions

When asked to document refinement notes, follow these steps:

1. **Record Session Metadata**
   Note the date, attendees, and duration. This helps track who was part of decisions and when discussions happened.

2. **List Stories Discussed**
   For each story, capture the outcome: estimated points, refined status, key discussion points, and any modifications made to the original scope.

3. **Document Questions Raised**
   Questions that couldn't be answered in the session need owners and due dates. Don't let them disappear.they often block sprint planning.

4. **Capture Decisions Made**
   Record any scope decisions, technical approaches agreed upon, or priority changes. These decisions are valuable context that gets lost without documentation.

5. **Note Action Items**
   Any follow-up work needed before stories are sprint-ready: mockups to create, technical spikes to run, stakeholders to consult.

6. **Flag Blocked Stories**
   Clearly identify stories that can't proceed until blockers are resolved. Include what the blocker is and who owns resolution.

7. **Plan Next Session**
   Note what should be refined next and any preparation needed.

## Output Template

# Refinement Notes: [Date]

## Session Info

| Attribute | Value |
|-----------|-------|
| **Date** | [Date and time] |
| **Duration** | [X minutes] |
| **Facilitator** | [Name] |
| **Sprint Preparing For** | [Sprint number] |

### Attendees

- [x] [Name, Role]
- [x] [Name, Role]
- [x] [Name, Role]
- [ ] [Name, Role] *(absent)*

---

## Summary

**Stories Discussed:** [X]
**Stories Refined (Ready):** [X]
**Stories Needing More Work:** [X]
**Total Points Estimated:** [X]

---

## Stories Refined

### [STORY-XXX]: [Story Title]

| Attribute | Value |
|-----------|-------|
| **Points** | [X] |
| **Status** | Ready / Needs Work / Blocked |
| **Assignee** | [If known] |

**Discussion Notes:**
- [Key point discussed]
- [Key point discussed]

**Scope Changes:**
- [Any changes from original story]

**Acceptance Criteria Confirmed:**
- [x] [Criterion 1]
- [x] [Criterion 2]
- [ ] [Criterion needs clarification]

---

### [STORY-XXX]: [Story Title]

| Attribute | Value |
|-----------|-------|
| **Points** | [X] |
| **Status** | Ready / Needs Work / Blocked |
| **Assignee** | [If known] |

**Discussion Notes:**
- [Key point discussed]
- [Key point discussed]

**Scope Changes:**
- [Any changes from original story]

**Acceptance Criteria Confirmed:**
- [x] [Criterion 1]
- [x] [Criterion 2]

---

### [STORY-XXX]: [Story Title]

| Attribute | Value |
|-----------|-------|
| **Points** | [X] |
| **Status** | Ready / Needs Work / Blocked |
| **Assignee** | [If known] |

**Discussion Notes:**
- [Key point discussed]
- [Key point discussed]

**Scope Changes:**
- [Any changes from original story]

---

## Stories Summary Table

| Story | Title | Points | Status | Notes |
|-------|-------|--------|--------|-------|
| [STORY-XXX] | [Title] | [X] | Ready | [Brief note] |
| [STORY-XXX] | [Title] | [X] | Ready | [Brief note] |
| [STORY-XXX] | [Title] | . | Needs Work | [What's needed] |
| [STORY-XXX] | [Title] | . | Blocked | [Blocker] |

---

## Questions Raised

| Question | Raised By | Owner | Due Date | Status |
|----------|-----------|-------|----------|--------|
| [Question 1] | [Name] | [Name] | [Date] | Open |
| [Question 2] | [Name] | [Name] | [Date] | Open |
| [Question 3] | [Name] | [Name] | [Date] | Resolved |

### Question Details

**Q: [Question 1]**
- Context: [Why this came up]
- Impact: [What's blocked until answered]
- Notes: [Any partial answers or direction]

---

## Decisions Made

| Decision | Context | Made By |
|----------|---------|---------|
| [Decision 1] | [Why we decided this] | [Name/Team] |
| [Decision 2] | [Why we decided this] | [Name/Team] |

---

## Action Items

| Action | Owner | Due Date | Status |
|--------|-------|----------|--------|
| [Action 1] | [Name] | [Date] | Not Started |
| [Action 2] | [Name] | [Date] | Not Started |
| [Action 3] | [Name] | [Date] | In Progress |

---

## Blocked Stories

| Story | Blocker | Owner | Expected Resolution |
|-------|---------|-------|---------------------|
| [STORY-XXX] | [What's blocking] | [Name] | [Date/unknown] |

---

## Parking Lot

<!-- Topics raised but deferred -->

- [Topic 1]: [Why deferred]
- [Topic 2]: [Why deferred]

---

## Next Session

**Date:** [Next refinement date]
**Stories to Prepare:**
- [STORY-XXX]: [Title]
- [STORY-XXX]: [Title]

**Preparation Needed:**
- [Who needs to do what before next session]

---

*Notes captured by [Name] on [Date].*

## Example Output

<details>
<summary>Refinement Notes: January 14, 2026</summary>

# Refinement Notes: January 14, 2026

## Session Info

| Attribute | Value |
|-----------|-------|
| **Date** | January 14, 2026, 2:00 PM EST |
| **Duration** | 45 minutes |
| **Facilitator** | Maya Chen (Scrum Master) |
| **Sprint Preparing For** | Sprint 15 (Jan 20 - Feb 2) |

### Attendees

- [x] Alex Rivera, Engineering Lead
- [x] Jordan Kim, Senior Engineer
- [x] Sam Patel, Engineer
- [x] Taylor Brooks, Product Manager
- [x] Maya Chen, Scrum Master
- [ ] Chris Wong, Engineer *(on PTO)*

---

## Summary

**Stories Discussed:** 5
**Stories Refined (Ready):** 3
**Stories Needing More Work:** 1
**Blocked Stories:** 1
**Total Points Estimated:** 13

---

## Stories Refined

### USER-342: Add CSV Export to Reports Dashboard

| Attribute | Value |
|-----------|-------|
| **Points** | 3 |
| **Status** | Ready |
| **Assignee** | Jordan |

**Discussion Notes:**
- Export should include all visible columns, respecting current filters
- Max export size: 10,000 rows (show warning, not error, at limit)
- File naming convention: `report-{report-name}-{date}.csv`
- Team agreed to use existing CSV library (PapaParse) for consistency

**Scope Changes:**
- Originally included Excel export.moved to separate story for future sprint

**Acceptance Criteria Confirmed:**
- [x] Export button visible on reports dashboard
- [x] CSV includes all visible columns with headers
- [x] Current filters applied to export
- [x] Large export shows warning but completes
- [x] Filename follows naming convention

---

### USER-345: Implement Password Reset Rate Limiting

| Attribute | Value |
|-----------|-------|
| **Points** | 5 |
| **Status** | Ready |
| **Assignee** | Sam |

**Discussion Notes:**
- Limit: 5 reset requests per email per hour
- After limit hit: show generic "check your email" message (no indication of limiting for security)
- Rate limit data stored in Redis with 1-hour TTL
- Security team reviewed and approved approach

**Scope Changes:**
- None

**Acceptance Criteria Confirmed:**
- [x] Max 5 reset requests per email per hour
- [x] User sees same message whether limited or not (security)
- [x] Rate limit resets after 1 hour
- [x] Admin dashboard shows rate limit events for monitoring

---

### USER-347: Profile Page Loading Performance

| Attribute | Value |
|-----------|-------|
| **Points** | 5 |
| **Status** | Ready |
| **Assignee** | Alex |

**Discussion Notes:**
- Current load time: 3.2 seconds average
- Target: Under 1 second for 90th percentile
- Main issue: N+1 query for user's projects
- Solution: Eager loading + pagination (show first 10 projects, load more on scroll)
- Jordan suggested we add performance test to prevent regression

**Scope Changes:**
- Added acceptance criterion for performance test

**Acceptance Criteria Confirmed:**
- [x] Profile page loads in <1 second (p90)
- [x] Initial load shows first 10 projects
- [x] Additional projects load on scroll (infinite scroll)
- [x] Performance test added to CI pipeline

---

### USER-348: User Settings Redesign

| Attribute | Value |
|-----------|-------|
| **Points** | . |
| **Status** | Needs Work |
| **Assignee** | TBD |

**Discussion Notes:**
- Story is too large.team estimated 13+ points
- Decision: Split into 3 smaller stories
  - USER-348a: Settings navigation restructure (3 pts)
  - USER-348b: Notification preferences panel (5 pts)
  - USER-348c: Privacy settings panel (3 pts)
- Taylor will create the split stories with UX guidance

**Scope Changes:**
- Entire story being split

**Acceptance Criteria Confirmed:**
- [ ] Pending split into smaller stories

---

### USER-350: Dark Mode Toggle

| Attribute | Value |
|-----------|-------|
| **Points** | . |
| **Status** | Blocked |
| **Assignee** | TBD |

**Discussion Notes:**
- Design team hasn't provided dark mode color palette yet
- Can't estimate until we know scope of color changes
- Some components may need redesign (charts, badges with colored backgrounds)

**Blocker:**
- Missing design specs.blocked on design team

---

## Stories Summary Table

| Story | Title | Points | Status | Notes |
|-------|-------|--------|--------|-------|
| USER-342 | CSV Export for Reports | 3 | Ready | Excel export moved to future |
| USER-345 | Password Reset Rate Limiting | 5 | Ready | Security team approved |
| USER-347 | Profile Page Performance | 5 | Ready | Added perf test criterion |
| USER-348 | User Settings Redesign | . | Needs Work | Splitting into 3 stories |
| USER-350 | Dark Mode Toggle | . | Blocked | Waiting on design specs |

---

## Questions Raised

| Question | Raised By | Owner | Due Date | Status |
|----------|-----------|-------|----------|--------|
| Should CSV export include hidden columns? | Jordan | Taylor | Jan 15 | Open |
| What's the plan for internationalization of exported dates? | Sam | Taylor | Jan 15 | Open |
| Can we get design specs for dark mode by Thursday? | Maya | Design Lead | Jan 16 | Open |

### Question Details

**Q: Should CSV export include hidden columns?**
- Context: Users can hide columns in the report view. Should hidden columns appear in export?
- Impact: Minor.doesn't block story, but affects implementation detail
- Notes: Taylor leaning toward "export matches what you see" but will confirm with customers

**Q: What's the plan for internationalization of exported dates?**
- Context: We have users in multiple locales. Dates in CSV might be ambiguous.
- Impact: Could affect USER-342 scope
- Notes: Options: ISO 8601 dates (unambiguous) or locale-specific with locale in filename

---

## Decisions Made

| Decision | Context | Made By |
|----------|---------|---------|
| Use ISO 8601 dates for CSV exports | Locale-specific dates too confusing; ISO is unambiguous | Team consensus |
| Split USER-348 into 3 stories | Original story too large (13+ points) | Team consensus |
| Add performance test to USER-347 | Prevent regression after optimization | Jordan's suggestion, team agreed |

---

## Action Items

| Action | Owner | Due Date | Status |
|--------|-------|----------|--------|
| Create split stories for USER-348 | Taylor | Jan 15 | Not Started |
| Answer CSV hidden columns question | Taylor | Jan 15 | Not Started |
| Follow up with design on dark mode specs | Maya | Jan 16 | Not Started |
| Update USER-342 with ISO 8601 date decision | Jordan | Jan 14 | Not Started |

---

## Blocked Stories

| Story | Blocker | Owner | Expected Resolution |
|-------|---------|-------|---------------------|
| USER-350 | Missing dark mode design specs | Design Lead | Jan 16 (Maya to follow up) |

---

## Parking Lot

- **Mobile responsive settings:** Jordan raised that settings page isn't mobile-friendly. Agreed to create a separate story rather than expand USER-348 scope. Taylor to add to backlog.
- **Export to Google Sheets:** Customer request came in during session. Taylor will assess priority and create story if warranted.

---

## Next Session

**Date:** January 21, 2026, 2:00 PM EST
**Stories to Prepare:**
- USER-348a, 348b, 348c: Split settings stories (after Taylor creates them)
- USER-350: Dark mode (if design specs received)
- USER-352: Bulk user invite (Taylor to write story by Thursday)

**Preparation Needed:**
- Taylor: Create split stories for USER-348 by Thursday
- Maya: Confirm design specs timeline for dark mode
- Chris: Review notes and raise any concerns async (returning from PTO)

---

*Notes captured by Maya Chen on January 14, 2026.*

</details>

## Real-World Examples

See this skill applied to three different product contexts:

<details>
<summary>Storevine (B2B): Storevine B2B ecommerce platform . Campaigns v1.1 sprint refinement session</summary>

**Prompt:**

```
/refinement-notes

Session: Campaigns v1.1 refinement
Date: July 22, 2026, 10:00 AM, 60 minutes
Sprint preparing for: Sprint 12 . Campaigns v1.1
Facilitator: Growth PM

Stories on the agenda:
1. CAM-088: EU merchant GDPR consent data model
2. CAM-089: Per-campaign open rate and click rate analytics
3. CAM-090: Follow-on experiment . 3 vs. 5 products in guided template
4. CAM-091: Abandoned cart email trigger

Key constraints:
- Legal has not yet signed off on the EU consent model (CAM-088)
- Backend Engineer flagged ambiguity on the open rate denominator
  (CAM-089): Amplitude delivered-event count vs. SendGrid recipient count
- CAM-091 may need to be split . scope spans 4 engineering domains

Need: full refinement notes for Sprint 12 planning.
```

---

**Output:**

# Refinement Notes: July 22, 2026

</details>

<details>
<summary>Brainshelf (Consumer): Brainshelf consumer PKM app . Sprint 9 refinement for Resurface v2 improvements</summary>

**Prompt:**

```
/refinement-notes

sprint 9 refinement for resurface v2. session was april 15, 2026.
45 minutes. priya facilitated.

stories discussed:
1. RSF-010: embedding migration (tfidf → openai text-embedding-3-small)
   . BLOCKED, waiting on openai api key + budget approval from marco
2. RSF-011: in-app resurfacing card on home screen . Ready, 5 pts [fictional]
3. RSF-012: cadence experiment (daily vs 3x/week, larger sample) .
   Ready, 3 pts [fictional]
4. RSF-013: small-library handling (users with <20 items, shorter
   exclusion window) . Needs Work, alex wants to see the data first

questions raised: should the in-app card show different items than
the email digest or the same items? what's the minimum library size
where tfidf actually produces useful results?

decision: in-app card shows different items (complementary, not
duplicate).
```

---

**Output:**

# Refinement Notes: April 15, 2026

</details>

<details>
<summary>Workbench (Enterprise): "Workbench enterprise collaboration platform: Blueprints v1.1 backlog refinement session"</summary>

**Prompt:**

```
/refinement-notes

I just ran the v1.1 refinement session. Here are the details:

**Session info:**
- Date: May 26, 2026
- Duration: 60 minutes
- Attendees: Rachel V. (PM, facilitator), Karen L. (Eng Lead), Tomás G. (Design), Nate P. (Backend), Aisha K. (Frontend), Leo M. (Data)

**Stories refined (6):**

1. BLUE-201: Approval action bar redesign -- promote Reject and Request Changes to primary visibility
   - Points: 3 (was 2 from retro; increased after discussion of animation transitions)
   - Ready for sprint

2. BLUE-202: Audit trail export (CSV) -- compliance officer can export all Blueprint lifecycle events for a date range
   - Points: 8
   - Ready for sprint
   - Note: Nate P. flagged that the current audit log stores events in an append-only format optimized for writes, not reads. The export query will need a read-optimized view or materialized table.

3. BLUE-203: Audit trail export (PDF) -- formatted PDF export for regulatory submissions
   - Points: 5
   - Blocked -- depends on BLUE-202 (CSV export provides the data layer); also needs legal review of the PDF format for FDA/SOX compliance

4. BLUE-204: Configurable wizard threshold -- template admins can set the section count at which the wizard auto-disables (default: 12)
   - Points: 2
   - Ready for sprint

5. BLUE-205: Approver-visible completeness score -- display per-section quality indicators in the approval review view
   - Points: 8
   - Ready for sprint (design review scheduled for May 28)
   - Note: Tomás G. proposed a progress bar showing "% sections with 20+ words" plus yellow warning badges on sections below threshold. Karen L. asked whether the threshold should be configurable -- team decided to hardcode 20 words for v1.1 and make it configurable in v1.2 if needed.

6. BLUE-206: Compliance officer role -- new RBAC role with template-lock and audit-export permissions
   - Points: 13
   - Blocked -- depends on BLUE-202 (audit export) for the export permission; also needs Karen L. to design the RBAC extension architecture

**Questions raised:**
- Should the audit trail export include section-level edit history or just lifecycle events? (Decision: lifecycle events only for v1.1; section-level history deferred to version history feature)
- Should the completeness score be visible to authors during editing, or only to approvers? (Decision: approvers only for now; author-visible is a future consideration)
- What happens to in-flight Blueprints when a compliance officer locks a template? (Parked for BLUE-206 design)

**Decisions made:**
- Wizard threshold default stays at 12 (consistency with v1) but is now admin-configurable
- Completeness word-count threshold is hardcoded at 20 words for v1.1
- Audit trail export scope is lifecycle events only (not section edit history)

Please generate the full refinement notes.
```

**Output:**

# Refinement Notes: May 26, 2026

</details>

## Quality Checklist

Before finalizing, verify:

- [ ] All discussed stories have outcomes recorded
- [ ] Open questions have owners assigned
- [ ] Decisions are captured with enough context
- [ ] Blocked stories are clearly flagged
- [ ] Notes are understandable to someone who wasn't there

## Output Format

Use the template in `references/TEMPLATE.md` to structure the output.
