/pair-process-refine-story — Story Refinement (single Draft→Ready)

Transform a user story from rough breakdown (Draft) into a development-ready specification (Ready). This is THE single Draft→Ready path — no separate "make-ready" skill exists and none is ever born (R3.12, D24); refinement IS the transition (canonical-states.md). Section-level idempotency — see idempotency convention: each refinement section is checked before acting; partial refinements resume from the first missing section, an already-Ready story is confirmed and exits.

Process Profile

<!-- process-step: id=refine-story -->

Executable form of the refine-story step, and a composer of define-subdomains, define-bounded-contexts. A direct invocation while a step is disabled by the project's profile warns and asks for confirmation; a composed one never prompts — it degrades exactly as a step that is not installed. No section ⇒ no-op. See process-profile gate.

Composed Skills

Skill	Type	Required
/pair-capability-grill	Capability	Yes — phase 0 shared-understanding sync (R3.11 alignment gate). If not installed, warn and fall back to the per-step approval gates.
/process-map-subdomains	Capability	Optional — functional/domain placement (Step 2), scoped to the story. If not installed, warn and skip domain placement.
/process-map-contexts	Capability	Optional — touched-context mapping (Step 3), scoped; feeds the coupling dimension. If not installed, warn and skip.
/pair-capability-classify	Capability	Optional — shift-left classification matrix into the story body (Step 3b). If not installed, warn and continue.
/pair-capability-write-issue	Capability	Yes — creates or updates the story issue in the PM tool

Arguments

Argument	Required	Description
$story	No	Story identifier (e.g., #42). If omitted, the skill selects the highest-priority Draft 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 the Draft macrostate (the board's Todo/backlog column via the state mapping — symmetric with Step 5's Ready→Refined). 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.

Phase 0: Shared-Understanding Sync (grill — BLOCKING)

This is the R3.11 AI↔human alignment gate — a prerequisite, not optional. No DoR section is authored until shared understanding is explicit; it is the reason no separate "make-ready" step exists (D24). Phase 0 runs between Step 0 (selection) and Step 1 (detection): the already-Ready check below is a light read of the body to decide whether to skip the sync — Step 1's detection table is where that state is formally determined.

1. Check: Has phase 0 already reached explicit shared understanding this session, or does a prior /pair-capability-grill sync handoff for this story exist in .pair/working/, or is the story already Ready (Step 1 confirms-and-exits)?
2. Skip: If shared understanding is already confirmed (or the story is already Ready), move to Step 1.
3. Act: Is /pair-capability-grill installed?
   • Yes: Compose /pair-capability-grill with $mode: sync, $story: [story-id], and $context: <current story body> so grill doesn't re-fetch it. Grill systematically covers all six aspects (goal, AC, edge cases, dependencies, design, risks) one question at a time and returns the alignment synthesis pre-mapped to the Refined template sections. Resume: if a prior sync was interrupted, its partial synthesis handoff is loaded and the sync resumes from the first open aspect — prior answers are not re-asked.
   • No: Warn (/pair-capability-grill not installed — skipping the phase 0 sync; alignment falls to the per-step human-judgment gates in Steps 2–4) and proceed; the explicit approval gates in Steps 2–4 remain the alignment mechanism.
4. Verify: /pair-capability-grill returned explicit shared understanding (grill never auto-exits on an empty queue — only an explicit human "yes" ends it), or the skip was warned. Without shared understanding → HALT: refinement does not proceed on an unaligned story.

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
   Design flag	Has a Design: line under Technical Analysis → Implementation Approach, set to not required or required — reference: <link> (DoR criterion 6, definition-of-ready-and-done.md)
   Doc team flag	Has a Doc team: line under Technical Analysis → Implementation Approach, set to non richiesta or richiesta — team: <team name> (a row of Notion Globale - Teams without the Team prefix; never Tech) (DoR criterion 7, definition-of-ready-and-done.md)
   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 Ready. 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 Ready — 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: Domain placement (functional). Is /process-map-subdomains installed? Compose /process-map-subdomains with $scope: [the business capability this story touches] — scoped to the story, never $scope: all (that is /pair-process-bootstrap-only). It classifies the touched capability as core/supporting/generic with a Volatility rating; that placement feeds the Business impact dimension of the classification matrix (Step 3b) and the volatility input to coupling (Step 3). Not installed, or no domain artifacts and no PRD/initiatives to classify from → degrade: skip domain placement with a note, still produce the functional analysis.

4. 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?

5. 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, Technical Risks, and the Design flag 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.
   • Design flag (DoR criterion 6): set the Design: line under Implementation Approach to not required when the approach is understood, or required — reference: <link> when a design doc/spike is needed — per definition-of-ready-and-done.md. This is the criterion Step 5 verifies as the sixth DoR criterion.
   • Doc team flag (DoR criterion 7): set the Doc team: line under Implementation Approach to richiesta — team: <team name> (a row of Notion Globale - Teams without the Team prefix — today Corsi, Growth, User, Social, B2B, Amministrazione; never Tech, which produces the guide rather than reading it) when the story introduces a feature usable by a non-technical team or changes an operational flow for one, otherwise non richiesta (refactor, internal change, bugfix with no perceivable flow change) — criterion in way-of-working.md, guide format in feature-guide-template.md. Decide it with the developer — never default to non richiesta silently: an unasked flag is a flag that produces no guide. When set to richiesta, the guide becomes a Done condition for the story (its link is attached to the issue).
   • Reference architecture.md and tech-stack.md.
2. Act: Touched-context mapping (technical). Is /process-map-contexts installed? Compose /process-map-contexts with $scope: [the contexts/services this story touches] — scoped, never $scope: all (that is /pair-process-bootstrap-only). It maps the touched subdomains to bounded contexts and assesses each relationship (integration strength, socio-technical distance, volatility) to derive a balanced/unbalanced verdict. When it reports an unbalanced integration this story introduces — strong coupling toward a distant and/or volatile context — record it as a row in the Technical Risks and Mitigation table (D38): the coupling risk this story adds, its impact, and the mitigation. This same map-contexts output feeds the Coupling balance dimension of the classification matrix (Step 3b) — refine-story runs no coupling assessment of its own; the inputs come from the scoped map-contexts output and the subdomain catalog volatility (D24). Not installed, or no domain artifacts → coupling is "not assessed", excluded from the matrix max, never blocks (D21).
3. Act: Present technical analysis (strategy, key components, integration points, and any coupling risk from the mapping) to developer for validation.
4. 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 /pair-capability-classify installed?
2. Skip: If not installed, warn (/pair-capability-classify not installed — skipping the shift-left risk matrix; classify at review time) and move to Step 4.
3. Act: Compose /pair-capability-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's ## Classification section — the first-class template slot in user-story-template.md (D22) — and, the first time, proposes the ## Tag Projection declaration before emitting any tag (adoption-gated). The Coupling balance dimension is fed by the scoped /process-map-contexts output from Step 3 (and subdomain volatility from Step 2); with no such output it is "not assessed" and excluded from the tier max (D38, D21). An unbalanced/volatile integration recorded as a risk in Step 3 therefore also raises the coupling dimension here — contributing to the tier via the existing max rule (D38). No tech/risk-matrix.md ⇒ KB defaults, matrix only, no tags (D21).
4. Verify: The story body's ## Classification section carries the matrix (or the skip was warned). /pair-capability-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 (resolve override-first — template resolution) Refined template:
   • Functional sections first: Story Statement → Epic Context → Classification (the Step 3b matrix) → Acceptance Criteria → Definition of Done → Story Sizing → Dependencies → Validation → Notes.
   • Technical sections last: Technical Analysis → (Task Breakdown added later by /pair-process-plan-tasks).
2. Act: Compose /pair-capability-write-issue with:
   • $type: story
   • $content: the assembled refined story body
   • $id: the story identifier (update mode — story already exists)
   • $status: Ready — pass it only when a board state maps to the Ready macrostate (a presence check on the state-mapping, not a resolution). /pair-capability-write-issue owns the board-field write: it resolves Ready to the target board state via the canonical-states.md writing rule (first board state mapped to Ready; e.g. Refined on pair's own board) and updates the Status field (its Step 6). Omit $status when no board state maps to Ready (a minimal board, D4): the completed DoR sections on the body are themselves the readiness signal per the definition-of-ready-and-done.md Readiness Fallback, and omitting it avoids /pair-capability-write-issue's unmapped-macrostate HALT (its Step 6). Idempotent: a story already at Ready is confirmed, not re-moved — refine-story runs no board-field write of its own (D24).
3. Verify: Either /pair-capability-write-issue wrote the board state resolved from $status: Ready (mapping present), or (no mapping, $status omitted) all seven DoR criteria are satisfied on the body as the readiness signal.

Step 6: Already-Ready 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 Ready. 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 /pair-capability-write-issue with $type: story, $id: [story-id], and updated $content.

4. Verify: Story updated.

Output Format

STORY REFINEMENT COMPLETE:
├── Story:    [#ID: Title]
├── Status:   [Ready | Updated | Ready (DoR-on-body — no board mapping)]
├── Sync:     [shared understanding confirmed | grill skipped — per-step gates]
├── Sections: [N/N complete]
├── Matrix:   [risk:<tier> · cost:<class> | classify not installed — no matrix]
├── Domain:   [subdomain placement + touched contexts | map-* not installed — skipped]
├── Sizing:   [X points — fits sprint: Yes/No]
├── PM Tool:  [Issue updated — #ID]
└── Next:     /pair-process-plan-tasks to create task breakdown

HALT Conditions

• No Draft stories in backlog (Step 0) — nothing to refine.
• Story not found (Step 0) — invalid $story identifier.
• No shared understanding (Phase 0) — /pair-capability-grill sync ended without an explicit human "yes"; refinement never proceeds on an unaligned story.
• 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 /pair-capability-write-issue not installed / PM tool not accessible → produce the refined story content, ask developer to update manually) for the standard scenarios. Additional cases:

• /pair-capability-grill not installed (Phase 0): warn and skip the sync; the per-step human-judgment approval gates in Steps 2–4 remain the alignment mechanism — refinement still completes.
• /process-map-subdomains / /process-map-contexts not installed, or no domain artifacts (Steps 2–3): the functional and technical analysis sections are still produced; domain placement and touched-context mapping are skipped with a note, and the coupling dimension is "not assessed" (never a HALT).
• /pair-capability-classify not installed (Step 3b): refinement completes without a matrix; the skip is flagged in the summary and the ## Classification section stays empty.
• No state mapping resolves to Ready (Step 5): the completed DoR sections on the body are the readiness signal (definition-of-ready-and-done.md Readiness Fallback) — not an error.
• 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

• The single Draft→Ready path (R3.12, D24): refinement IS the transition to Ready — there is no separate "make-ready" skill and none is ever added. Phase 0's grill sync is the R3.11 alignment gate that makes this one skill sufficient.
• R3.11 is "not optional" as a gate, not as a specific skill: the AI↔human alignment gate always runs. When /pair-capability-grill is installed it runs the systematic phase 0 sync; when it is not, the explicit per-step human-judgment approval gates in Steps 2–4 are the accepted satisfaction of R3.11 (graceful-degradation convention). What is never skipped is explicit human alignment before the story reaches Ready.
• This skill modifies PM tool state — it updates story issues and transitions the item to Ready.
• Composes, never re-derives: domain placement comes from /process-map-subdomains, touched-context/coupling from /process-map-contexts, the matrix from /pair-capability-classify — refine-story orchestrates them scoped to the story and owns no assessment criteria of its own (D24).
• Template ordering (Step 5) positions Technical Analysis as the bridge to Task Breakdown (added by /pair-process-plan-tasks).
• INVEST validation: the refined story must satisfy Independent, Negotiable, Valuable, Estimable, Small, Testable criteria.
• The /pair-process-refine-story skill handles the transition from Initial Breakdown template format to Refined template format.