issue-refinement

Transforms raw GitHub issues or feature requests into well-structured user stories with acceptance criteria, applied in the DISCUSS phase.

When to use

Transforming a raw issue into an implementable user story
Checking INVEST compliance of an existing story
Detecting the 8 story antipatterns (Implement-X, Vague Persona, etc.)
Applying a splitting pattern (by workflow step, business rule, data variation, interface, AC, happy/sad path)
Validating the 8 DoR (Definition of Ready) items before entering the DESIGN phase

Entry contract

Raw GitHub issue or story in progress
Triaged and prioritised (issue that has passed the DISCOVER phase)

Exit contract

User story in the format As a {persona}, I want {capability}, so that {benefit}
≥ 3 acceptance criteria in Given/When/Then or bullet-list format
DoR 8 items validated
Effort estimate (XS, S, M, L — XL forbidden without splitting)

Invariants

Story is a unit of value — A story is NOT a task, a ticket, or a technical instruction
Specific persona — never “a user”, “someone”, or “the system”
Capability = observable behaviour — never implement, create, call, build as the capability
XL = must be split before DoR — Any XL-estimated story cannot reach status/ready
6 INVEST criteria — Independent, Negotiable, Valuable, Estimable, Small, Testable — all must pass

Why this shape

The DISCUSS phase produces stories, not technical specifications. A well-formed story aligns the team on the value to deliver without prescribing implementation. Acceptance criteria derived from domain examples ensure that expected behaviour can be validated by a domain expert with no code knowledge.

« The goal of refinement is shared understanding, not a perfect document. »

The 6 splitting patterns (by workflow step, business rule, data variation, interface, AC, happy/sad path) allow any XL story to be reduced into independently deliverable S/M stories.

Allowed customisation

User story template (L1)
Additional splitting patterns (L2)
Minimum AC threshold (default: 3) (L2)