Validate User Stories

Validate User Stories — Entry Orchestrator

⚠️ Execution Discipline

You are now operating under this skill's instructions exclusively. BEFORE generating ANY output, verify:

1. Have I read the workflow file for this step?
2. Have I completed ALL prior stages per the state file?
3. 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

⚡ Step 3.5: Pre-Flight Checks

🚀 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

1. Always build fresh registry — never trust existing .meta/story-registry.md. Read actual files.
2. Ring 1 first — if Ring 1 fails, skip Ring 2-3. Don't waste effort on format when structure is broken.
3. Evidence for every finding — no finding without citing specific story, AC, and evidence.
4. Impact statements — every finding says "This means..." (what happens if not fixed).
5. Creation-validation alignment — if stories were created by generate-user-stories, Categories 1-9 should PASS. Any failure = creation skill bug. Flag it.
6. Fix first, present second — never present output the tool knows has quality issues.

📎 Related Skills

INTAKE COMPLETE → Read workflows/01-validate.md to begin