Story Verification Skill

Validate Stories/Tasks with explicit GO/NO-GO verdict, Readiness Score, and Anti-Hallucination verification.

Purpose & Scope

• •Validate Story plus child Tasks against industry standards and project patterns
• •Calculate Penalty Points for violations, then auto-fix to reach 0 points
• •Delegate to ln-002-best-practices-researcher for creating documentation (guides, manuals, ADRs, research)
• •Support Plan Mode: show audit results, wait for approval, then fix
• •Approve Story after fixes (Backlog -> Todo) with tabular output summary

When to Use

• •Reviewing Stories before approval (Backlog -> Todo)
• •Validating implementation path across Story and Tasks
• •Ensuring standards, architecture, and solution fit
• •Optimizing or correcting proposed approaches

Penalty Points System

Goal: Quantitative assessment of Story/Tasks quality. Target = 0 penalty points after fixes.

Workflow:

1. •Audit: Calculate penalty points for all 17 criteria
2. •Fix: Auto-fix and zero out points
3. •Report: Total Before -> 0 After

Mode Detection

Detect operating mode at startup:

Plan Mode Active:

• •Phase 1-2: Full audit (discovery + research + penalty calculation)
• •Phase 3: Show results + fix plan -> WAIT for user approval
• •Phase 4-5: After approval -> execute fixes

Normal Mode:

• •Phase 1-5: Standard workflow without stopping
• •Automatically fix and approve

Workflow Overview

Phase 1: Discovery & Loading

Step 1: Configuration & Metadata Loading

• •Auto-discover configuration: Team ID (docs/tasks/kanban_board.md), project docs (CLAUDE.md), epic from Story.project
• •Load metadata only: Story ID/title/status/labels, child Task IDs/titles/status/labels
• •Expect 3-8 implementation tasks; record parentId for filtering
• •Rationale: keep loading light; full descriptions arrive in Phase 2

Phase 2: Research & Audit

Always execute for every Story - no exceptions.

Step 1: Domain Extraction

• •Extract technical domains from Story title + Technical Notes + Implementation Tasks
• •Load pattern registry from references/domain_patterns.md
• •Scan Story content for pattern matches via keyword detection
• •Build list of detected domains requiring documentation

Step 2: Documentation Delegation

• •For EACH detected pattern, delegate to ln-002:
  code

  Skill(skill="ln-002-best-practices-researcher",
        args="doc_type=[guide|manual|adr] topic='[pattern]'")
  

• •Receive file paths to created documentation (docs/guides/, docs/manuals/, docs/adrs/, docs/research/)

Step 3: Research via MCP

• •Query MCP Ref for industry standards: ref_search_documentation(query="[topic] RFC OWASP best practices 2025")
• •Query Context7 for library versions: resolve-library-id + query-docs
• •Extract: standards (RFC numbers, OWASP rules), library versions, patterns

Step 3.5: Anti-Hallucination Verification

• •Scan Story/Tasks for technical claims (RFC references, library versions, security requirements)
• •Verify each claim has MCP Ref/Context7 evidence
• •Flag unverified claims for correction
• •Status: VERIFIED (all sourced) or FLAGGED (list unverified)

Step 4: Penalty Points Calculation

• •Evaluate all 17 criteria against Story/Tasks
• •Assign penalty points per violation (CRITICAL=10, HIGH=5, MEDIUM=3, LOW=1)
• •Calculate total penalty points
• •Build fix plan for each violation

Phase 3: Audit Results & Fix Plan

Display audit results:

• •Penalty Points table (criterion, severity, points, description)
• •Total: X penalty points
• •Fix Plan: list of fixes for each criterion

Mode handling:

• •IF Plan Mode: Show results + "After your approval, changes will be applied" -> WAIT
• •ELSE (Normal Mode): Proceed to Phase 4 immediately

Phase 4: Auto-Fix

Execute fixes for ALL 17 criteria on the spot.

• •Execution order (6 groups):
  1. •Structural (#1-#4) — Story/Tasks template compliance
  2. •Standards (#5) — RFC/OWASP compliance FIRST (before YAGNI/KISS!)
  3. •Solution (#6) — Library versions
  4. •Workflow (#7-#13) — Test strategy, docs integration, size, cleanup, YAGNI, KISS, task order
  5. •Quality (#14-#15) — Documentation complete, hardcoded values
  6. •Traceability (#16-#17) — Story-Task alignment, AC coverage (LAST, after all fixes)
• •Use Auto-Fix Actions table below as authoritative checklist
• •Zero out penalty points as fixes applied
• •Test Strategy section must exist but remain empty (testing handled separately)

Phase 5: Approve & Notify

• •Set Story + all Tasks to Todo (Linear); update kanban_board.md with APPROVED marker
• •Add Linear comment with full validation summary:
  • •Penalty Points table (Before -> After = 0)
  • •Auto-Fixes Applied table
  • •Documentation Created table (docs created via ln-002)
  • •Standards Compliance Evidence table
• •Display tabular output (Unicode box-drawing) to terminal
• •Final: Total Penalty Points = 0
• •Optional: If --execute flag provided, delegate to ln-400-story-executor to start execution immediately after approval

Auto-Fix Actions Reference

Structural (#1-#4)

Standards (#5)

Solution (#6)

Workflow (#7-#13)

Quality (#14-#15)

Traceability (#16-#17)

Maximum Penalty: 50 points

Final Assessment Model

Outputs after all fixes applied:

Readiness Score Calculation

Readiness Score = 10 - (Penalty Points / 5)

Anti-Hallucination Verification

Verify technical claims have evidence:

Status: VERIFIED (all claims sourced) or FLAGGED (unverified claims listed)

Task-AC Coverage Matrix

Output explicit mapping:

| AC | Task(s) | Coverage |
|----|---------|----------|
| AC1: Given/When/Then | T-001, T-002 | ✅ |
| AC2: Given/When/Then | T-003 | ✅ |
| AC3: Given/When/Then | — | ❌ UNCOVERED |

Coverage: {covered}/{total} ACs (target: 100%)

Self-Audit Protocol (Mandatory)

Before marking any criterion as complete, provide concrete evidence (doc path, MCP result, Linear update).

Definition of Done

• •Phase 1: Auto-discovery done; Story + Tasks metadata loaded; task count checked
• •Phase 2: Domain extraction complete; ln-002 delegated for docs; MCP research done; Anti-Hallucination verification done; Penalty Points calculated
• •Phase 3: Audit results shown; IF Plan Mode: user approved
• •Phase 4: All 17 criteria auto-fixed; Penalty Points = 0; Test Strategy empty; test tasks removed
• •Phase 5: Final Assessment output:
  yaml

  gate: GO | NO-GO
  readiness_score: {1-10}
  penalty_points: 0 (was {N})
  anti_hallucination: VERIFIED | FLAGGED
  ac_coverage: "{N}/{M} (100%)"
  ac_matrix:
    - ac: "AC1"
      tasks: ["T-001", "T-002"]
      status: covered
  

• •Story/Tasks set to Todo; kanban_board.md updated; Linear comment with Final Assessment added
• •Optional: If --execute flag, ln-400-story-executor invoked after approval

Example Workflow

Story: "Create user management API with rate limiting"

1. •Phase 1: Load metadata (5 Tasks, status Backlog)
2. •Phase 2:
   • •Domain extraction: REST API, Rate Limiting
   • •Delegate ln-002: creates Guide-05 (REST patterns), Guide-06 (Rate Limiting)
   • •MCP Ref: RFC 7231 compliance, OWASP API Security
   • •Context7: Express v4.19 (current v4.17)
   • •Penalty Points: 18 total (version=5, missing docs=5, structure=3, standards=5)
3. •Phase 3:
   • •Show Penalty Points table
   • •IF Plan Mode: "18 penalty points found. Fix plan ready. Approve?"
4. •Phase 4:
   • •Fix #6: Update Express v4.17 -> v4.19
   • •Fix #5: Add RFC 7231 compliance notes
   • •Fix #13: Add Guide-05, Guide-06 references
   • •Fix #17: Docs already created by ln-002
   • •All fixes applied, Penalty Points = 0
5. •Phase 5: Story -> Todo, tabular report

Template Loading

Templates: story_template.md, task_template_implementation.md

Loading Logic:

1. •Check if docs/templates/{template}.md exists in target project
2. •IF NOT EXISTS: a. Create docs/templates/ directory if missing b. Copy shared/templates/{template}.md → docs/templates/{template}.md c. Replace placeholders in the LOCAL copy:
   • •{{TEAM_ID}} → from docs/tasks/kanban_board.md
   • •{{DOCS_PATH}} → "docs" (standard)
3. •Use LOCAL copy (docs/templates/{template}.md) for all validation operations

Rationale: Templates are copied to target project on first use, ensuring:

• •Project independence (no dependency on skills repository)
• •Customization possible (project can modify local templates)
• •Placeholder replacement happens once at copy time

Reference Files

• •Final Assessment: references/readiness_scoring.md (GO/NO-GO rules, Readiness Score calculation)
• •Templates (centralized): shared/templates/story_template.md, shared/templates/task_template_implementation.md
• •Local copies: docs/templates/ (in target project)
• •Validation Checklists (Progressive Disclosure):
  • •references/verification_checklist_template.md (overview of 6 categories)
  • •references/structural_validation.md (criteria #1-#4)
  • •references/standards_validation.md (criterion #5)
  • •references/solution_validation.md (criterion #6)
  • •references/workflow_validation.md (criteria #7-#13)
  • •references/quality_validation.md (criteria #14-#15)
  • •references/traceability_validation.md (criteria #16-#17)
  • •references/domain_patterns.md (pattern registry for ln-002 delegation)
  • •references/penalty_points.md (penalty system details)
• •Linear integration: ../shared/templates/linear_integration.md

Version: 6.0.0 (Added GO/NO-GO verdict, Readiness Score, Anti-Hallucination verification based on BMAD validate-next-story methodology) Last Updated: 2026-01-29