story-quality_skill

Overview

This skill reviews user stories for quality, proper sizing, sequencing, and acceptance criteria before converting them to prd.json. It produces a clear, actionable quality report that lists issues per story and recommended fixes so stories are ready for autonomous implementation.

How this skill works

The skill reads the PRD or list of user stories and evaluates each story against concise quality rules: description clarity, scope size, dependency ordering, and acceptance criteria completeness. It flags problems, suggests specific splits or reordering, and adds precise, testable acceptance criteria including required checks like typechecks and browser verification for UI stories.

When to use it

• Before converting a PRD into prd.json for autonomous build loops
• When preparing stories for Ralph/Claude Code iterations
• During sprint planning to ensure stories are single-iteration scoped
• When acceptance criteria feel vague or untestable
• When stories may depend on schema, API, or other stories

Best practices

• Keep descriptions to 1-2 lines: 'As a X, I want Y so that Z'
• Limit each story to one implementable capability (one context window)
• Order stories: schema → backend → UI → integration
• Always include 'Typecheck passes' and add 'Verify in browser' for UI stories
• Make acceptance criteria specific, verifiable, and testable

Example use cases

• Review a feature backlog before handing to an autonomous agent to prevent failed iterations
• Split a large dashboard epic into database, API, UI, and integration stories
• Detect UI stories that reference APIs or schema that are not yet implemented
• Convert vague acceptance criteria into concrete testable checks
• Produce a story-by-story report for a product manager to revise quickly