Story Verification Skill

Story Verification

Validate stories, check test coverage gaps, verify PRP completeness, and assess development readiness.

Usage

/story-verify                       # Auto: validate all stories in project
/story-verify invest <id|all>       # INVEST criteria scoring
/story-verify coverage              # Map stories -> tests, show gaps
/story-verify prp                   # Check PRP completeness against stories
/story-verify ready <id>            # Development readiness assessment

Workflow

Step 1: Determine Mode

Parse $ARGUMENTS for explicit subcommand. If no arguments, run invest all as default.

Detect project context:

PROJECT_INFO=$(bash "$HOME/.claude/skills/story/lib/project-detector.sh")

Step 2: Route to Subcommand

Subcommand: `invest`

INVEST criteria validation — no Python scripts, pure template-based inline logic.

Process

Load story YAML from stories/yaml-source/US-XXXX.yaml (or all if "all")
Read templates/invest-checklist.md for scoring rules
Score each criterion (0-100):

| Criterion | Score 100 | Score 50 | Score 0 | | --------------- | ------------------------------------------ | ------------------------------------ | -------------------------------- | | Independent | No blocked_by, or only 1 external dep | 2-3 dependencies | Circular deps or >3 blockers | | Negotiable | "i_want" describes outcome/behavior | Mentions specific tech but flexible | Prescribes exact implementation | | Valuable | Clear "so_that" with measurable benefit | Vague benefit ("improve experience") | Missing "so_that" entirely | | Estimable | Has story_points + >=3 acceptance_criteria | Has points OR criteria, not both | Missing both points and criteria | | Small | 1-5 story points | 6-8 story points | >8 points (must split) | | Testable | All criteria have given/when/then | Some criteria missing parts | No given/when/then at all |

Overall score = average of 6 criteria
Pass: overall >= 70 AND all criteria >= 50

Output

Story US-XXXX: "View financial dashboard"
  I: 100  N: 100  V: 75  E: 100  S: 100  T: 100
  Overall: 96 — PASS

  Issues:
  - [Medium] Valuable: "so_that" could be more specific about measurable outcome

Auto-Fix Suggestions

| Issue | Fix | | ----------------------------------- | --------------------------------------------------------------- | | Missing "so_that" | Suggest based on persona goals and feature context | | Vague benefit | Add measurable outcome (number, percentage, time saved) | | Missing story points | Estimate from acceptance criteria count (1 criterion ≈ 1 point) | | Too few criteria | Suggest additional Given/When/Then from feature scope | | Implementation language in "i_want" | Rewrite to describe behavior, not code | | >8 points | Suggest story splitting strategy |

Subcommand: `coverage`

Map stories to test files and identify untested acceptance criteria.

Process

Load all story YAML files
For each story, search test directory for matching test file:
- Pattern: test_US_XXXX* (pytest) or US_XXXX*.test.* (jest)
For each acceptance criterion in the story:
- Search test files for matching test function (by criterion slug or docstring)
Build coverage matrix

Output

Read templates/coverage-matrix.md for output format.

Story Coverage Matrix
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

US-0001: View dashboard          [2/3 criteria covered]
  ✓ health score displayed       → test_dashboard_shows_health_score
  ✓ KPI pillars visible          → test_dashboard_shows_kpi_pillars
  ✗ color indicator correct      → NO TEST

US-0002: Upload document         [0/2 criteria covered]
  ✗ PDF accepted                 → NO TEST
  ✗ error on invalid file        → NO TEST

Summary: 2/5 criteria covered (40%)
Gap: 3 criteria need test stubs — run `/story tests US-0001 US-0002`

Subcommand: `prp`

Check PRP completeness against its source stories.

Process

Scan PRP directory (detected by project-detector.sh) for PRP files
For each PRP, extract referenced stories (look for US-XXXX patterns)
Cross-reference with story YAML files:
- Are all referenced stories defined?
- Do all stories have sufficient acceptance criteria?
- Are story dependencies resolvable?
Check PRP sections against PRP completeness checklist:
- Header with metadata
- Executive summary
- Requirements reference
- Architecture design
- Implementation plan (phased)
- Testing strategy
- Success criteria

Output

PRP-012: Financial Data Display
  Stories referenced: US-0010, US-0011, US-0012, US-0013
  ✓ All stories defined in YAML
  ✓ All stories have acceptance criteria
  ✗ US-0011 blocked_by US-0009 (not in scope — risk)
  ✓ PRP has all required sections
  ✗ Testing strategy missing E2E test plan

Subcommand: `ready`

Full readiness assessment for a story before implementation starts.

Process

Run invest validation (must pass)
Check dependencies: all blocked_by stories must be status done
Check test stubs exist (from /story tests)
Check PRP exists for the story's feature area
Check technical context (has enough detail for implementation)

Output

Read templates/readiness-checklist.md for format.

US-0012: Display financial data tables
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✓ INVEST validation: PASS (score: 92)
  ✓ Dependencies: US-0011 (done), US-0009 (done)
  ✗ Test stubs: NOT FOUND — run `/story tests US-0012`
  ✓ PRP: PRP-012 covers this story
  ✓ Technical context: FastAPI route + Jinja2 template

  Verdict: ALMOST READY — generate test stubs first

Template Locations

| Template | Purpose | File | | ------------------- | ---------------------------- | ---------------------------------- | | INVEST checklist | Scoring rules and thresholds | templates/invest-checklist.md | | Coverage matrix | Story-to-test mapping format | templates/coverage-matrix.md | | Readiness checklist | Dev readiness criteria | templates/readiness-checklist.md |

Agent Skills: Story Verification

Install this agent skill to your local

Skill Files