¶
Quick facts
Phase: Iterate | Version: 2.0.0 | Category: coordination | License: Apache-2.0
Refinement Notes¶
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:
Or reference the skill file directly: skills/iterate-refinement-notes/SKILL.md
Instructions¶
When asked to document refinement notes, follow these steps:
-
Record Session Metadata Note the date, attendees, and duration. This helps track who was part of decisions and when discussions happened.
-
List Stories Discussed For each story, capture the outcome: estimated points, refined status, key discussion points, and any modifications made to the original scope.
-
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.
-
Capture Decisions Made Record any scope decisions, technical approaches agreed upon, or priority changes. These decisions are valuable context that gets lost without documentation.
-
Note Action Items Any follow-up work needed before stories are sprint-ready: mockups to create, technical spikes to run, stakeholders to consult.
-
Flag Blocked Stories Clearly identify stories that can't proceed until blockers are resolved. Include what the blocker is and who owns resolution.
-
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¶
- [Name, Role]
- [Name, Role]
- [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¶
- [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¶
Refinement Notes: January 14, 2026
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¶
- Alex Rivera, Engineering Lead
- Jordan Kim, Senior Engineer
- Sam Patel, Engineer
- Taylor Brooks, Product Manager
- 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.
Real-World Examples¶
See this skill applied to three different product contexts:
Storevine (B2B): Storevine B2B ecommerce platform — Campaigns v1.1 sprint refinement session
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¶
Brainshelf (Consumer): Brainshelf consumer PKM app — Sprint 9 refinement for Resurface v2 improvements
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¶
Workbench (Enterprise): Workbench enterprise collaboration platform: Blueprints v1.1 backlog refinement session
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¶
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.