Refinement Notes
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:
-
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:
- [Criterion 1]
- [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:
- [Criterion 1]
- [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:
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:
- Export button visible on reports dashboard
- CSV includes all visible columns with headers
- Current filters applied to export
- Large export shows warning but completes
- 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:
- Max 5 reset requests per email per hour
- User sees same message whether limited or not (security)
- Rate limit resets after 1 hour
- 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:
- Profile page loads in <1 second (p90)
- Initial load shows first 10 projects
- Additional projects load on scroll (infinite scroll)
- 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 refinementDate: July 22, 2026, 10:00 AM, 60 minutesSprint preparing for: Sprint 12 . Campaigns v1.1Facilitator: Growth PM
Stories on the agenda:1. CAM-088: EU merchant GDPR consent data model2. CAM-089: Per-campaign open rate and click rate analytics3. CAM-090: Follow-on experiment . 3 vs. 5 products in guided template4. 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 marco2. 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 thanthe email digest or the same items? what's the minimum library sizewhere tfidf actually produces useful results?
decision: in-app card shows different items (complementary, notduplicate).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.