refine-story

name	refine-story
description	Refines a user story from Todo to Refined — Given-When-Then acceptance criteria, technical analysis, sprint readiness. Composes /write-issue. Not for sizing an already-refined story (use /estimate).
version	0.5.0
author	Foomakers

/refine-story — Story Refinement

Transform a user story from rough breakdown (Todo) into a development-ready specification (Refined). Section-level idempotency — see idempotency convention: each refinement section is checked before acting; partial refinements resume from the first missing section.

Composed Skills

Skill	Type	Required
/write-issue	Capability	Yes — creates or updates the story issue in the PM tool
/classify	Capability	Optional — shift-left classification matrix into the story body. If not installed, warn and continue.

Arguments

Argument	Required	Description
$story	No	Story identifier (e.g., #42). If omitted, the skill selects the highest-priority Todo story from the backlog.

Algorithm

Step 0: Story Selection

1. Check: Is $story provided?

2. Skip: If provided, load the story from the PM tool and proceed to Step 1.

3. Act: If not provided, query the PM tool for stories in Todo state. Apply selection criteria:

   • Priority: P0 > P1 > P2
   • Sprint need: stories required for upcoming sprint
   • Dependency chain: stories blocking other work

4. Act: Present recommendation and ask developer to confirm:

   Recommend refining Story #[ID]: [Title] (Priority: [P0/P1/P2]). Reason: [business value / sprint urgency / unblocks other work]. Proceed?

5. Verify: A story is identified (from $story or developer confirmation) and its current body is available for Step 1's section detection.

Step 1: Detect Refinement State

1. Check: Read the current story body and classify each section as present or missing:

   Section	Detection
   Story Statement	Has **As a** / **I want** / **So that** with non-placeholder content
   Epic Context	Has **Parent Epic** with actual link
   Acceptance Criteria (Given-When-Then)	Has **Given** / **When** / **Then** blocks
   Business Rules	Has non-placeholder business rules
   Edge Cases	Has non-placeholder edge case handling
   Technical Analysis	Has ### Implementation Approach or ### Strategy with content
   Technical Risks	Has risk table with entries
   Definition of Done	Has DoD checklist with items
   Story Sizing	Has **Final Story Points** with value
   Dependencies	Has dependency information
   Validation Strategy	Has testing approach

2. Act: Determine refinement state:

   • All sections present → story is already Refined. Offer selective update (Step 6).
   • Some sections present → partial refinement. Resume from first missing section (Steps 2–5).
   • No sections (only Initial Breakdown) → full refinement needed (Steps 2–5).

3. Verify: Refinement state determined. Report:

   Refinement state: [N/M sections complete]. [Resuming from: Section X | Full refinement | Already refined — offering update].

Step 2: Requirements Analysis

Skip if: Acceptance Criteria, Business Rules, and Edge Cases are all present.

1. Act: Expand the story scope into detailed, testable acceptance criteria:

   • Convert requirements into Given-When-Then scenarios.
   • Identify business rules with measurable criteria.
   • Address edge cases and error handling conditions.

2. Act: Domain check — if context-map.md (in .pair/adoption/product/) exists, read it (plus any linked subdomain/<slug>.context.md this story touches). When the story introduces or sharpens a domain term, update the map inline per the Context Map Maintenance guideline. When a proposed criterion conflicts with a registered rule, flag it citing that rule (and the DDR, when one exists) and resolve with the developer before proceeding. Skip this step entirely if the map doesn't exist — its absence is expected, not an error.

3. Act: Present the proposed criteria to the developer for validation:

   Proposed acceptance criteria for #[ID]: [List Given-When-Then scenarios] [Business rules] [Edge cases] Approve or adjust?

4. Verify: Human-judgment gate — the developer explicitly approves the presented Given-When-Then scenarios, business rules, and edge cases (or requests changes, looping back to Step 2's Act). Only an explicit approval finalizes the criteria.

Step 3: Technical Analysis

Skip if: Technical Analysis and Technical Risks are present.

1. Act: Assess the implementation approach:
   • Strategy: high-level technical approach and architecture alignment.
   • Key components: modules, integration points, data flow.
   • Risks: technical unknowns, complexity, dependencies.
   • Reference architecture.md and tech-stack.md.
2. Act: Present technical analysis to developer for validation.
3. Verify: Human-judgment gate — the developer explicitly approves the presented strategy, key components, and risks (or requests changes, looping back to Step 3's Act). Only an explicit approval finalizes the analysis.

Step 3b: Classification (shift-left matrix)

Skip if: the story body already carries a classification matrix section for the current model + adoption (deterministic — re-running yields the same matrix).

1. Check: Is /classify installed?
2. Skip: If not installed, warn (/classify not installed — skipping the shift-left risk matrix; classify at review time) and move to Step 4.
3. Act: Compose /classify with $context: refinement and $target: [story-id]. It applies the quality model to the story context, writes the matrix as 1 line + <details> into the story body (D22), and — the first time — proposes the ## Tag Projection declaration before emitting any tag (adoption-gated). No tech/risk-matrix.md ⇒ KB defaults, matrix only, no tags (D21).
4. Verify: The story body carries the classification matrix (or the skip was warned). /classify HALTs only if the quality model doc (#221) is absent — surface that pointer to the developer.

Step 4: Sprint Readiness

Skip if: Story Sizing, Dependencies, and Validation Strategy are present.

1. Act: Re-estimate story size with detailed requirements:
   • Apply refined sizing: XS(1), S(2), M(3), L(5), XL(8).
   • Assess sprint fit — split if oversized while preserving user value.
   • Map dependencies (prerequisite and dependent stories).
   • Define validation and testing strategy.
2. Act: Present sizing assessment to developer.
3. Verify: Human-judgment gate — the developer explicitly approves the sizing, dependencies, and validation strategy presented in Step 4's Act. Only an explicit approval confirms sprint readiness.

Step 5: Documentation and PM Tool Update

1. Act: Assemble the complete refined story body using the user-story-template.md Refined template:
   • Functional sections first: Story Statement → Epic Context → Acceptance Criteria → Definition of Done → Story Sizing → Dependencies → Validation → Notes.
   • Technical sections last: Technical Analysis → (Task Breakdown added later by /plan-tasks).
2. Act: Compose /write-issue with:
   • $type: story
   • $content: the assembled refined story body
   • $id: the story identifier (update mode — story already exists)
   • $status: Ready — transitions the project board field from Todo to Refined
3. Verify: Story updated in PM tool. Board status is Ready.

Step 6: Already-Refined Update (optional path)

Reached only when Step 1 detects all sections are present.

1. Act: Ask the developer which sections to update:

   Story #[ID] is already refined. Which sections need updating?

   1. Acceptance Criteria
   2. Technical Analysis
   3. Sprint Sizing
   4. All sections

2. Act: For selected sections, re-execute the corresponding step (2, 3, or 4).

3. Act: Compose /write-issue with $type: story, $id: [story-id], and updated $content.

4. Verify: Story updated.

Output Format

STORY REFINEMENT COMPLETE:
├── Story:    [#ID: Title]
├── Status:   [Refined | Updated]
├── Sections: [N/N complete]
├── Sizing:   [X points — fits sprint: Yes/No]
├── PM Tool:  [Issue updated — #ID]
└── Next:     /plan-tasks to create task breakdown

HALT Conditions

• No Todo stories in backlog (Step 0) — nothing to refine.
• Story not found (Step 0) — invalid $story identifier.
• PM tool not accessible — cannot read or update stories.
• Developer rejects criteria (Steps 2–4) — must resolve before proceeding.

Graceful Degradation

See graceful degradation (optional skill /write-issue not installed / PM tool not accessible → produce the refined story content, ask developer to update manually) for the standard scenarios. Additional cases:

• If adoption files (architecture, tech-stack) are not found, skip technical analysis alignment checks and warn.
• If context-map.md is not found, skip the domain check in Step 2 — its absence is the expected steady state, not an error.

Notes

• This skill modifies PM tool state — it updates story issues.
• Template ordering (Step 5) positions Technical Analysis as the bridge to Task Breakdown (added by /plan-tasks).
• INVEST validation: the refined story must satisfy Independent, Negotiable, Valuable, Estimable, Small, Testable criteria.
• The /refine-story skill handles the transition from Initial Breakdown template format to Refined template format.