| name | validate-user-stories |
| description | Audits existing user stories against 12 validation categories (9 per-story + 2 cross-story + 1 practitioner readability) and fixes failures. Builds a fresh registry from actual story files — never trusts existing registries. Works on any story set regardless of how stories were created. Use when asked to: validate stories, check stories, review stories, audit stories, fix stories, or improve story quality. |
Validate User Stories — Entry Orchestrator
⚠️ Execution Discipline
You are now operating under this skill's instructions exclusively.
BEFORE generating ANY output, verify:
- Have I read the workflow file for this step?
- Have I completed ALL prior stages per the state file?
- Has the user explicitly approved the last checkpoint?
If ANY answer is NO → stop. Read the correct workflow file.
NEVER generate validation reports without following the workflow files.
🎯 Purpose
Audit existing stories against 12 validation categories and fix failures.
Always builds a fresh registry from actual files — never trusts existing registries.
Works on any story set regardless of how stories were created.
What you'll get:
[output-folder]/validation-registry-[feature].md — fresh ground truth from actual files[output-folder]/Validation-Report-[Feature].md — full audit report
Core principle: A false pass means broken work enters the sprint. A false fail wastes rework and trust. Both are failures.
🔄 Workflow Chain
[You are here]
SKILL.md (Intake)
↓ reads
workflows/01-validate.md → builds fresh registry, runs 12 categories, generates report
↓ reads (if fixes needed)
workflows/02-fix.md → fixes failures in Ring order, re-validates
📥 Step 1: Three-Tier Scoping Gate
Tier 1: User-Provided Files (always included)
Story files or feature folder referenced by user. No confirmation needed.
Tier 2: Same-Folder Scan (user selects)
Glob parent folder(s). Look for: other stories in same feature folder, requirements doc, epic.
Present grouped. User selects. Unselected never read.
Tier 3: Workspace-Wide Search (opt-in only)
After Tier 2, offer broader search. If declined, proceed with Tier 1+2 only.
📂 Step 1.5: Load Project Context
IF project-context.md found: Read and extract personas, stack, conventions.
IF not found: Proceed without it.
📋 Step 2: Gather Context
For validation, I need:
1. Which stories? (single file / feature folder / all)
2. Requirements doc or epic? (for source verification — optional but improves quality)
3. Output folder for the validation report
🔀 Step 3: Mode Detection
| Mode | Signal | Route |
|---|
| VALIDATE | "validate", "check", "review", "audit" | workflows/01-validate.md |
| FIX | "fix", "improve", "update", "recover" | workflows/01-validate.md → workflows/02-fix.md |
⚡ Step 3.5: Pre-Flight Checks
| Check | Action if missing |
|---|
| At least 1 story file found | Required — ask |
| Feature name captured | Required — infer from folder or ask |
| Output folder confirmed | Required — ask |
| Requirements doc available? | Optional — source verification will be limited without it |
🚀 Step 4: Start Validation
Ready to validate.
Stories found: [count] files in [folder]
Requirements doc: ✅ Found / ❌ Not found (source verification limited)
Output folder: [path]
Starting validation...
Then read: workflows/01-validate.md
🚨 Critical Rules
- Always build fresh registry — never trust existing
.meta/story-registry.md. Read actual files.
- Ring 1 first — if Ring 1 fails, skip Ring 2-3. Don't waste effort on format when structure is broken.
- Evidence for every finding — no finding without citing specific story, AC, and evidence.
- Impact statements — every finding says "This means..." (what happens if not fixed).
- Creation-validation alignment — if stories were created by
generate-user-stories, Categories 1-9 should PASS. Any failure = creation skill bug. Flag it.
- Fix first, present second — never present output the tool knows has quality issues.
📎 Related Skills
| After validation... | Skill to suggest |
|---|
| Walk through findings interactively | /review-findings |
| Fix stories and audit for staleness | 02-fix.md → /document-audit |
| Modify a specific story | /generate-user-stories (modify mode) |
INTAKE COMPLETE → Read workflows/01-validate.md to begin
