story-readiness

Validate story files for implementation readiness and produce READY, NEEDS WORK, or BLOCKED verdicts.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/nevesb/idol-agency-maker --skill story-readiness-nevesb
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: story-readiness
Source: https://github.com/nevesb/idol-agency-maker/tree/main/.claude/skills/story-readiness
Command: npx skills add https://github.com/nevesb/idol-agency-maker --skill story-readiness-nevesb

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill prevents mid-sprint surprises and developer guesswork by validating that a user story contains all design, architecture, testing, and asset information required to begin implementation without interruptions.

Core Features & Use Cases

  • Comprehensive checklist that verifies GDD references, testable acceptance criteria, ADR status, TR-ID registry lookups, manifest version consistency, engine notes, estimates, scope boundaries, and dependency states.
  • Asset existence checks using globbing to confirm referenced assets are present and flag missing files.
  • Aggregate and sprint modes to validate a single story, all stories in a sprint, or every story in production, emitting per-story verdicts (READY / NEEDS WORK / BLOCKED) and detailed gap lists.
  • Director gate integration and escalation that respects review modes (solo/lean/full) and can spawn QA review tasks when required.
  • Read-only reporting that suggests fixes and offers to draft missing sections conversationally without writing files.

Quick Start

Run the story-readiness skill on a story path, sprint, or 'all', for example: /story-readiness production/epics/combat/story-001-basic-attack.md

Frequently Asked Questions about story-readiness

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

FAQPage Schema
How do I verify user stories are ready for implementation before sprint planning?

To verify user stories for implementation readiness, validate design references, ADR cross-references, acceptance criteria, manifest versions, asset existence, estimates, and dependencies. This produces per-story verdicts of READY, NEEDS WORK, or BLOCKED with detailed gap reports to prevent mid-sprint interruptions.

What is story readiness validation and what problem does it solve?

Story readiness validation checks that user stories contain all required design, architecture, testing, and asset information. It solves the problem of developer guesswork and mid-sprint surprises by confirming implementation can begin without interruptions, producing detailed gap lists for missing elements.

How do I check if referenced assets exist and manifest versions are consistent across stories?

Checking asset existence uses globbing to confirm referenced assets are present and flags missing files. Manifest version consistency is validated alongside ADR status and TR-ID registry lookups during the readiness check, ensuring all cross-references and dependencies are resolved before implementation.

Can I validate all stories in a sprint or production environment at once?

Yes, aggregate and sprint modes allow validating a single story, all stories in a sprint, or every story in production using an all-stories glob. Each mode emits per-story verdicts with detailed gap lists, enabling batch verification across the entire project backlog.

How do I handle unresolved questions and missing sections in user story files?

Unresolved questions and missing sections are reported as gaps in the readiness verdict. The read-only reporting suggests fixes and offers to draft missing sections conversationally without writing files, maintaining a safe review process while highlighting what needs attention.

Does story readiness validation integrate with director review gates and escalation workflows?

Director gate integration respects review modes including solo, lean, and full, spawning QA review tasks when required. Sprint escalation warnings are produced for blocked stories, ensuring proper workflow gates are enforced before implementation begins.