Story Readiness

Story Readiness

What Is This

The Story Readiness skill is a verification tool for the Happycapy Skills platform, designed to evaluate whether a story file is ready for development. Its core function is to analyze a designated story file, or a set of stories, and determine if all required elements for implementation are present. It checks for embedded Game Design Document (GDD) requirements, Architectural Decision Record (ADR) references, engine notes, clear acceptance criteria, and the absence of unresolved design questions. The output is a verdict for each story: READY, NEEDS WORK, or BLOCKED, each accompanied by a list of specific gaps if the story is not ready.

Story Readiness is a read-only skill. It will never edit your story files or make changes to your project artifacts. Instead, it provides clear diagnostic feedback and can prompt the user to fill in any missing information.

Why Use It

Development teams often encounter friction when stories are sent to implementation before they are fully specified. This can result in ambiguous requirements, missing acceptance criteria, or open design questions that lead to context switching and mid-sprint interruptions. The Story Readiness skill eliminates these issues by enforcing a readiness gate before work begins.

By ensuring that each story is implementation-ready, teams can:

• Minimize wasted effort and rework caused by unclear requirements.
• Prevent blockers that delay development.
• Foster clearer communication between design, engineering, and product teams.
• Increase sprint predictability and developer confidence.

This skill is especially valuable in environments with cross-functional teams, complex dependencies, or where stories are authored by multiple stakeholders.

How to Use It

The Story Readiness skill is invoked through the Happycapy Skills platform and accepts an argument specifying the story scope:

story-readiness [story-file-path | 'all' | 'sprint']

• Use a specific file path to check a single story (e.g., story-readiness stories/ui/button.md).
• Use all to check every story in the repository.
• Use sprint to check all stories assigned to the current sprint.

Argument Handling Example: If no argument is provided, the skill will prompt the user to specify a target using the AskUserQuestion tool.

Review Mode Resolution: At startup, the skill determines the review mode as follows:

1. If called with --review [full|lean|solo], that value is used.
2. Otherwise, it reads production/review-mode.txt for the mode.
3. If neither is set, it defaults to lean.

Sample Code Invocation:

story-readiness stories/gameplay/inventory-system.md

Sample Output:

Verdict: NEEDS WORK
Gaps:
- Missing clear acceptance criteria
- No ADR reference for inventory persistence
- Open design question: How are item stacks visualized?

When to Use It

Use the Story Readiness skill in the following scenarios:

• Before assigning a story to a developer or sprint.
• When a team member asks, "Is this story ready to implement?" or "Can I start on this story?"
• During sprint planning or grooming sessions as a quality gate.
• When reviewing a batch of stories for an upcoming milestone.

It is especially useful to run this skill after design discussions, before work is handed over to engineering, to ensure all details have been captured.

Important Notes

• Read-only: This skill does not modify any files. It strictly analyzes and reports.
• Comprehensive Checks: It validates for the presence of GDD requirements, ADR references, engine notes, acceptance criteria, and ensures there are no unresolved design questions.
• Structured Output: For each story, you receive a clear verdict (READY, NEEDS WORK, BLOCKED) and a detailed gap analysis.
• User Interaction: If the target story is not specified, the skill will prompt for input.
• Review Modes: The review mode (full, lean, solo) affects the depth of checks performed and is resolved once per run.
• Integration: Compatible with other Happycapy Skills tools and adheres strictly to the provided argument hints and category conventions.

By incorporating Story Readiness into your workflow, you can ensure that every story entering development is fully specified, reducing friction and accelerating delivery.