refine-story-functionally

Refines user stories with discovery probes and testable Gherkin acceptance criteria.

Updated Dec 1, 2025
One-click install
npx skills add https://github.com/jterratsdev/smart-deployment --skill refine-story-functionally-jterratsdev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: refine-story-functionally
Source: https://github.com/jterratsdev/smart-deployment/tree/main/.setup-agents/skills/refine-story-functionally
Command: npx skills add https://github.com/jterratsdev/smart-deployment --skill refine-story-functionally-jterratsdev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often write vague user stories with untestable acceptance criteria, leading to rework, missed requirements, and unclear handoffs between business analysts, architects, and QA. This Skill structures functional story refinement so every story reaches a verifiable Ready state before technical work begins. ## Core Features & Use Cases - Discovery Probes: Systematically surfaces hidden requirements by questioning persona, scope, triggers, data, and dependencies before any acceptance criteria are written. - Acceptance Criteria Quality Framework: Enforces INVEST principles and testable Gherkin (Given/When/Then) criteria, rejecting vague statements and requiring Privacy ACs for PII-touching stories. - Local Backlog Persistence: Records refined stories to the repo-resident backlog via sf setup-agents task create, keeping git as the source of truth instead of an external tracker. - Use Case: A business analyst receives a rough feature request, runs the discovery probes to clarify scope and edge cases, writes Gherkin acceptance criteria, and persists a Ready story that the technical architect can pick up for impact analysis. ## Quick Start Ask the assistant to refine a story functionally by running discovery probes and writing testable Gherkin acceptance criteria, then save it to the local backlog.

Frequently Asked Questions about refine-story-functionally

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

FAQPage Schema
How do I write testable acceptance criteria for a user story?

Write each acceptance criterion in Gherkin format: Given a precondition, When an action occurs, Then an observable outcome results. Reject vague statements like "works correctly" and restate them as outcomes QA can verify.

What is the INVEST criteria for user stories?

INVEST means a story is Independent, Negotiable, Valuable, Estimable, Small, and Testable. This Skill applies each as a quality gate, handing oversized stories to decomposition and underspecified ones back for more discovery.

Where are refined stories stored with this workflow?

Refined stories are stored in the repo-resident backlog at .setup-agents/state/tasks.jsonl using the sf setup-agents task create command. Jira or Atlassian MCP mirroring is optional; the local git-backed backlog remains authoritative.

When is a user story considered Ready for development?

A story is Ready when it has a linked persona, stated scope and non-goals, acceptance criteria passing the quality framework, listed data objects, declared dependencies, and a sizing signal. Missing any item means Not Ready.

What happens to stories that are too large or technically unclear?

Stories sized M or larger, or those with technical unknowns, are handed to the refine-story-technically skill for impact analysis and technical tasking. Oversized stories may first go to decomposition to fit one iteration.