story-refiner

Refine raw user stories into sprint-ready backlog items with INVEST checks and Given/When/Then criteria.

Updated May 9, 2026
One-click install
npx skills add https://github.com/GustavoGutierrez/engineering-skills --skill story-refiner-gustavogutierrez
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: story-refiner
Source: https://github.com/GustavoGutierrez/engineering-skills/tree/main/skills/story-refiner
Command: npx skills add https://github.com/GustavoGutierrez/engineering-skills --skill story-refiner-gustavogutierrez

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It removes ambiguity from user stories by refining them into INVEST-aligned, testable backlog items with clear acceptance criteria and explicit edge cases.

Core Features & Use Cases

  • INVEST-based refinement: evaluates independence, negotiability, value, estimability, size, and testability, then applies targeted fixes.
  • Gap and risk detection: identifies missing context such as vague criteria, happy-path-only descriptions, hidden dependencies, and oversized scope.
  • Structured sprint-ready output: produces a refined user story plus Given/When/Then acceptance criteria, negative scenarios, dependencies, assumptions, and open questions.
  • Splitting oversized work: recommends 2–3 smaller stories when the original work is too large for a sprint.

Quick Start

Use the story-refiner skill to refine this draft user story into sprint-ready backlog format with INVEST review, acceptance criteria, and edge scenarios.

Frequently Asked Questions about story-refiner

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refine user stories into sprint-ready backlog items?

To refine user stories into sprint-ready backlog items, apply INVEST checks to evaluate independence, value, and testability, then generate Given/When/Then acceptance criteria covering negative paths and dependencies. This removes ambiguity and ensures stories are actionable.

What is the INVEST checklist used for in backlog refinement?

The INVEST checklist in backlog refinement evaluates user stories for Independence, Negotiability, Value, Estimability, Size, and Testability. It identifies gaps like vague criteria or oversized scope, applying targeted fixes to produce structured, testable items.

How do I write acceptance criteria that cover edge cases and unhappy paths?

Writing acceptance criteria that cover edge cases involves generating observable Given/When/Then statements that explicitly define negative scenarios and error handling. This ensures user stories include unhappy paths, dependencies, and missing validation details.

How do I split an oversized user story for a sprint?

To split an oversized user story for a sprint, analyze its scope against INVEST criteria to detect if it is too large. The refinement process then suggests 2-3 smaller stories, ensuring each split item remains testable and independently estimable.

Can I use Gherkin Given/When/Then format for structuring user story acceptance criteria?

Yes, you can use Gherkin Given/When/Then format to structure user story acceptance criteria. This format produces observable, testable conditions that explicitly cover happy paths, negative scenarios, and edge cases required for sprint readiness.

What gaps are commonly missed when writing user stories for product planning?

Common gaps missed when writing user stories for product planning include happy-path-only descriptions, missing validation, hidden dependencies, vague criteria, and absent error handling details. Detecting these gaps ensures complete sprint-ready backlog items.