Story Refinement

A structured process for refining user stories from initial idea to implementation-ready. The story moves through three phases, each with defined ownership and review gates.

Phases Overview

A story is Ready for Execution only when all three phases are complete and approved.

Phase 1: Functional Requirements (The "What" - User Perspective)

Purpose

Define what the user will experience. This phase captures the problem being solved and the desired outcome from the user's point of view.

Process

Step 1: Collaborative Drafting (Human + Copilot)

An interactive session to explore and articulate the requirements together.

Copilot's role during drafting:

• •Ask clarifying questions to understand the problem and context
• •Probe for edge cases and alternative scenarios
• •Suggest ways to articulate requirements clearly
• •Help identify what's in scope vs out of scope
• •Challenge assumptions constructively
• •Offer examples and counter-examples to sharpen definitions

The session produces a draft containing:

1. •

   User Story Statement

   • •As a [type of user], I want [goal] so that [benefit]
   • •Keep it focused on one coherent piece of value
2. •

   Acceptance Criteria

   • •Written from the user's perspective
   • •Describe what happens, not how it's implemented
   • •Each criterion is independently verifiable
   • •Good: "I can see my progress from previous sessions"
   • •Bad: "Progress is loaded from a JSON file" (implementation detail)
3. •

   User Experience Walkthrough

   • •Step-by-step description of the user's interaction
   • •Include the happy path and key alternative paths
   • •For CLI: show example commands and outputs
   • •For UI: describe screens, states, and transitions
4. •

   Out of Scope

   • •Explicitly list what this story does NOT include
   • •Helps prevent scope creep during implementation

Step 2: Human Review

The human reviews the draft for accuracy and completeness:

• •Does this capture what I actually want?
• •Have we missed any important scenarios?
• •Is the scope right - not too big, not too small?
• •Am I comfortable committing to this definition?

Step 3: Product Review (Copilot as Senior PM)

Once the human approves the draft, the copilot reviews it wearing their Senior Product Manager hat - someone experienced in UX and product development.

Review lens:

• •User value and problem-solution fit
• •Clarity and testability of acceptance criteria
• •UX coherence and usability
• •Completeness of the user journey
• •Potential user confusion or friction points
• •Whether edge cases are adequately addressed

Review Checklist:

• • User story is focused on a single piece of value
• • The "so that" clearly articulates the benefit
• • Acceptance criteria are user-facing, not technical
• • Acceptance criteria are independently testable/verifiable
• • UX walkthrough covers the happy path completely
• • UX walkthrough addresses error cases and edge cases
• • The user journey feels coherent and intuitive
• • Out of scope section prevents ambiguity
• • No implementation details have leaked into this phase
• • A new team member could understand what "done" looks like

Output of review: Copilot presents findings and recommendations. Human decides whether to address feedback or proceed.

Phase 1 Complete When

• •Draft created collaboratively
• •Human has reviewed and approved
• •Product review conducted and feedback addressed (or consciously deferred)
• •GitHub issue updated with Functional Requirements section

Phase 2: Technical Requirements (The "What" - System Perspective)

Purpose

Define what the system must satisfy to deliver the functional requirements. This phase bridges user needs and implementation constraints.

Process

Step 1: Copilot Drafts Technical Requirements

Based on the approved functional requirements, the copilot translates user needs into system terms.

The draft contains:

1. •

   Domain Concepts

   • •New or modified entities, value objects, aggregates
   • •Business rules and invariants
   • •Ubiquitous language additions or changes
2. •

   System Behaviours

   • •Use cases to be added or modified
   • •Commands vs queries (CQS)
   • •Domain events to be raised
3. •

   Data Requirements

   • •New data to be captured or persisted
   • •Data migrations needed for existing data
   • •Event schema changes (remember: capture full context)
4. •

   Integration Points

   • •External systems or APIs involved
   • •New ports/adapters required
   • •Contract changes
5. •

   Non-Functional Requirements

   • •Performance expectations
   • •Security considerations
   • •Observability needs (logging, metrics)
   • •Error handling requirements
6. •

   Dependencies

   • •New libraries needed (justify why standard library won't work)
   • •Version constraints

Step 2: Human Review

The human reviews the draft for alignment and completeness:

• •Does this accurately translate what I want into system terms?
• •Are there technical decisions here I disagree with?
• •Is the scope of technical work appropriate for the story?
• •Are there implications I hadn't considered?

Step 3: Architecture Review (Copilot as Senior Engineer)

Once the human approves the draft, the copilot reviews it wearing their Senior Software Engineer / Architect hat - someone experienced in system design and long-term maintainability.

Review lens:

• •Alignment with existing architecture and patterns
• •Domain model consistency and evolution
• •Data integrity and migration safety
• •Security implications
• •Operational concerns (observability, error handling)
• •Simplicity - is this the simplest solution that works?
• •Technical debt and future maintainability

Review Checklist:

• • All functional requirements are addressed
• • Domain concepts align with existing domain model
• • Ubiquitous language is consistent with codebase
• • No unnecessary complexity introduced
• • Data migration strategy is clear and safe (if applicable)
• • Events capture sufficient context for future needs
• • Security implications considered
• • No new dependencies without justification
• • Aligns with hexagonal architecture patterns
• • Error handling strategy is clear
• • Observability needs are addressed

Output of review: Copilot presents findings and recommendations. Human decides whether to address feedback or proceed.

Phase 2 Complete When

• •Technical requirements drafted by Copilot
• •Human has reviewed and approved
• •Architecture review conducted and feedback addressed (or consciously deferred)
• •GitHub issue updated with Technical Requirements section

Phase 3: Implementation Plan (The "How")

Owner: Copilot Reviewer: Human

Purpose

Define the step-by-step approach to implementing the story while keeping the codebase in a working state at every step.

Constraints

• •Main stays green: Every step must leave the code compiling, tests passing, and linting clean
• •Small, atomic changes: Each step is a potential commit point and safely revertible
• •TDD rhythm: Steps follow Red → Green → Refactor with review gates
• •Design before code: Types and interfaces defined before implementation

Contents

1. •

   Step-by-Step Breakdown Each step should specify:

   • •What will be done
   • •What tests will be written/modified
   • •What the commit message would be
   • •Whether this step closes the issue or is intermediate
2. •

   Walking Skeleton (if applicable)

   • •For new features: identify the minimal end-to-end path
   • •Include: configuration, logging, health checks, CI considerations
3. •

   Risk Areas

   • •Parts of the implementation that are uncertain
   • •Spike work that might be needed
   • •Areas where the plan might need adjustment
4. •

   Verification Strategy

   • •How each acceptance criterion will be verified
   • •Test levels: use case tests, adapter tests, unit tests
   • •Manual verification steps (if any)

Step Format Example

Step 1: Define the ReviewSession aggregate
- Add ReviewSession entity with fields: ID, DeckID, StartedAt, CompletedAt, Cards
- Add ReviewSessionRepository port interface
- Create in-memory adapter (returns empty/error for now)
- Wire into composition root
- Test: ReviewSession can be created with valid deck
- Commit: "feat(domain): add ReviewSession aggregate (#42)"
- Status: Intermediate (does not close issue)

Review Checklist (Human reviewing Copilot's draft)

• • Each step keeps main green
• • Steps are small enough to be atomic commits
• • TDD approach is clear for each step
• • All acceptance criteria have verification coverage
• • Risk areas are identified
• • No big-bang changes; complexity is introduced incrementally
• • Commit messages follow conventional commits with issue references

Output

The GitHub issue is updated with the Implementation Plan section.

Ready for Execution Checklist

Before marking a story as ready for execution, verify:

• • Phase 1 Complete: Functional requirements reviewed and approved
• • Phase 2 Complete: Technical requirements reviewed and approved
• • Phase 3 Complete: Implementation plan reviewed and approved
• • GitHub Issue Updated: All three sections are documented in the issue
• • No Open Questions: All ambiguities resolved or explicitly deferred

Once all boxes are checked, the story transitions from Refinement to Execution.

Anti-Patterns to Avoid

1. •Skipping to implementation - Resist the urge to start coding before the story is fully refined
2. •Technical acceptance criteria - Keep Phase 1 user-focused; technical details belong in Phase 2
3. •Big-bang implementation plans - If a step touches more than 2-3 files, break it down further
4. •Implicit scope - If something isn't in scope, list it in "Out of Scope"
5. •Optimistic planning - Identify risks and uncertainties upfront; don't hide complexity