Paths: File paths (shared/ , references/ , ../ln-* ) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

Story Verification Skill

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

Inputs

Input Required Source Description

storyId

Yes args, git branch, kanban, user Story to process

Resolution: Per shared/references/input_resolution_pattern.md — Story Resolution Chain. Status filter: Backlog

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.

Severity Points Description

CRITICAL 10 RFC/OWASP/security violations

HIGH 5 Outdated libraries, architecture issues

MEDIUM 3 Best practices violations

LOW 1 Structural/cosmetic issues

Workflow:

• Audit: Calculate penalty points for all 22 criteria

• Fix: Auto-fix and zero out points

• 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-6: After approval -> execute fixes

Normal Mode:

• Phase 1-6: Standard workflow without stopping

• Automatically fix and approve

Plan Mode: Progress Tracking with TodoWrite

When operating in any mode, skill MUST create detailed todo checklist tracking ALL phases and steps.

Rules:

• Create todos IMMEDIATELY before Phase 1

• Each phase step = separate todo item

• Mark in_progress before starting step, completed after finishing

Todo Template (~21 items):

Phase 1: Discovery & Loading

• Auto-discover configuration (Team ID, docs)
• Load Story metadata (ID, title, status, labels)
• Load Tasks metadata (1-8 implementation tasks)

Phase 2: Research & Audit

• Extract technical domains from Story/Tasks
• Delegate documentation creation to ln-002
• Research via MCP Ref (RFC, OWASP, library versions)
• Verify technical claims (Anti-Hallucination)
• Calculate Penalty Points (22 criteria)

Phase 3: Audit Results & Fix Plan

• Display Penalty Points table and fix plan
• Wait for user approval (Plan Mode only)

Phase 4: Auto-Fix (8 groups)

• Fix Structural violations (#1-#4)
• Fix Standards violations (#5)
• Fix Solution violations (#6, #21)
• Fix Workflow violations (#7-#13)
• Fix Quality violations (#14-#15)
• Fix Dependencies violations (#18-#19/#19b)
• Fix Risk violations (#20)
• Fix Traceability violations (#16-#17)

Phase 5: Agent Review (MANDATORY — delegated to ln-311)

• [MANDATORY] Invoke ln-311-agent-reviewer with story_ref + tasks_ref
• [MANDATORY] Process and apply accepted suggestions to Story/Tasks

Phase 6: Approve & Notify

• Set Story/Tasks to Todo status in Linear
• Update kanban_board.md with APPROVED marker
• Add Linear comment with validation summary
• Display tabular output to terminal

Workflow

Phase 0: Tools Config

MANDATORY READ: Load shared/references/tools_config_guide.md , shared/references/storage_mode_detection.md , and shared/references/input_resolution_pattern.md

Read docs/tools_config.md (bootstrap if missing per tools_config_guide.md). Extract: task_provider = Task Management → Provider (linear | file ).

All subsequent phases use task_provider to select operations per storage_mode_detection.md.

Phase 1: Discovery & Loading

Step 1: Resolve storyId (per input_resolution_pattern.md):

• IF args provided → use args

• ELSE IF git branch matches feature/{id}-* → extract id

• ELSE IF kanban has exactly 1 Story in [Backlog] → suggest

• ELSE → AskUserQuestion: show Stories from kanban filtered by [Backlog]

Step 2: 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

• IF task_provider = linear : get_issue(storyId)

• list_issues(parentId=storyId)

• IF task_provider = file : Read story.md

• Glob("docs/tasks/epics//stories//tasks/*.md")

• Expect 1-8 implementation tasks; record parentId for filtering

• Rationale: keep loading light; full descriptions arrive in Phase 2

Phase 2: Research & Audit

MANDATORY READ: Load references/phase2_research_audit.md for complete research and audit procedure:

• Domain extraction from Story/Tasks

• Documentation delegation to ln-002 (guides/manuals/ADRs)

• MCP research (RFC/OWASP/library versions via Ref + Context7)

• Anti-Hallucination verification (evidence-based claims)

• Penalty Points calculation (22 criteria, see Auto-Fix Actions Reference in same file)

Always execute for every Story - no exceptions.

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 22 criteria on the spot.

• Execution order (8 groups):

• Structural (#1-#4) — Story/Tasks template compliance + AC completeness/specificity

• Standards (#5) — RFC/OWASP compliance FIRST (before YAGNI/KISS!)

• Solution (#6, #21) — Library versions, alternative solutions

• Workflow (#7-#13) — Test strategy, docs integration, size, cleanup, YAGNI, KISS, task order

• Quality (#14-#15) — Documentation complete, hardcoded values

• Dependencies (#18-#19/#19b) — Story/Task independence (no forward deps), parallel group validity

• Risk (#20) — Implementation risk analysis (after dependencies resolved, before traceability)

• Verification (#22) — AC verify methods exist for all task ACs (test/command/inspect)

• Traceability (#16-#17) — Story-Task alignment, AC coverage quality (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: Agent Review (MANDATORY — DO NOT SKIP)

MANDATORY STEP: This phase MUST execute regardless of Phase 4 results. Skipping agent review is a workflow violation. If agents unavailable, ln-311 returns SKIPPED — acceptable. But invocation MUST happen.

Invoke Skill(skill="ln-311-agent-reviewer", args="{storyId}") .

• ln-311 gets Story/Task references from Linear, builds prompt with references, runs agents in parallel, persists prompts and results in .agent-review/{agent}/ .

• If verdict = SUGGESTIONS → apply ACCEPTED suggestions to Story/Tasks text.

• If verdict = SKIPPED (no agents or all failed) → proceed to Phase 6 unchanged.

• Display: agent stats from ln-311 output: "Agent Review: {agent_stats summary}"

Phase 6: Approve & Notify

• Set Story + all Tasks to Todo; update kanban_board.md with APPROVED marker

• IF task_provider = linear : save_issue({id, state: "Todo"}) for Story + each Task

• IF task_provider = file : Edit Status: line to Todo in story.md + each task file

• Add validation summary comment:

• IF task_provider = linear : create_comment({issueId, body}) on Story

• IF task_provider = file : Write comment to docs/tasks/epics/.../comments/{ISO-timestamp}.md

• Content: Penalty Points table (Before -> After = 0), Auto-Fixes Applied, Documentation Created (via ln-002), Standards Compliance Evidence

• Display tabular output (Unicode box-drawing) to terminal

• Final: Total Penalty Points = 0

• Recommended next step: ln-400-story-executor to start Story execution

Auto-Fix Actions Reference

MANDATORY READ: Load references/phase2_research_audit.md for complete 21-criteria table with:

• Structural (#1-#4): Story/Task template compliance

• Standards (#5): RFC/OWASP compliance

• Solution (#6, #21): Library versions, alternatives

• Workflow (#7-#13): Test strategy, docs, size, YAGNI/KISS, task order

• Quality (#14-#15): Documentation, hardcoded values

• Traceability (#16-#17): Story-Task alignment, AC coverage

• Dependencies (#18-#19/#19b): No forward dependencies

• Risk (#20): Implementation risk analysis

Maximum Penalty: 88 points (sum of all 22 criteria; #20 capped at 15)

Final Assessment Model

Outputs after all fixes applied:

Metric Value Meaning

Gate GO / NO-GO Final verdict for execution readiness

Readiness Score 1-10 Quality confidence level

Penalty Points 0 (after fixes) Validation completeness

Anti-Hallucination VERIFIED / FLAGGED Technical claims verified

AC Coverage 100% (N/N) All ACs mapped to Tasks

Readiness Score Calculation

Readiness Score = 10 - (Penalty Points / 5)

Before/After diagnostic: Phase 3 calculates initial Penalty Points and Readiness Score (Before). Phase 4 auto-fixes reduce penalties to 0, yielding Readiness Score = 10 (After). Both values reported in Final Assessment for transparency.

Gate Condition

GO Penalty Points = 0 after Phase 4 (Readiness Score = 10)

NO-GO Any criterion FLAGGED as unfixable (see Critical Rules)

Anti-Hallucination Verification

Verify technical claims have evidence:

Claim Type Verification

RFC/Standard reference MCP Ref search confirms existence

Library version Context7 query confirms version

Security requirement OWASP/CWE reference exists

Performance claim Benchmark/doc reference

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

Task-AC Coverage Matrix

Output explicit mapping:

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

Self-Audit Protocol (Mandatory)

Verify all 22 criteria (#1-#22) from Auto-Fix Actions pass with concrete evidence (doc path, MCP result, Linear update) before proceeding to Phase 6.

Critical Rules

• All 22 criteria MUST be verified with concrete evidence (doc path, MCP result, Linear update) before Phase 6 (Self-Audit Protocol)

• Fix execution order is strict: Structural -> Standards -> Solution -> Workflow -> Quality -> Dependencies -> Risk -> Traceability (standards before YAGNI/KISS)

• Never approve with Penalty Points > 0; all violations must be auto-fixed to zero. If auto-fix is impossible for a criterion (e.g., MCP Ref unavailable, external dependency), mark as FLAGGED with reason — penalty stays, Gate = NO-GO, user must resolve manually

• Test Strategy section must exist but remain empty (testing handled separately by other skills)

• In Plan Mode, MUST stop after Phase 3 and wait for user approval before applying any fixes

Definition of Done

• Phases 1-6 completed: metadata loaded, research done, penalties calculated, fixes applied, agent review done, Story approved.

• Penalty Points = 0 (all 22 criteria fixed). Readiness Score ≥ 5.

• Anti-Hallucination: VERIFIED (all claims sourced via MCP).

• AC Coverage: 100% (each AC mapped to ≥1 Task).

• Agent Review: ln-311 invoked; suggestions aggregated, validated, accepted applied (or SKIPPED if no agents).

• Story/Tasks set to Todo; kanban updated; Linear comment with Final Assessment posted.

Example Workflow

Story: "Create user management API with rate limiting"

• Phase 1: Load metadata (5 Tasks, status Backlog)

• 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)

• Phase 3:

• Show Penalty Points table

• IF Plan Mode: "18 penalty points found. Fix plan ready. Approve?"

• 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

• Phase 5: Agent review (delegated to ln-311-agent-reviewer → apply accepted suggestions)

• Phase 6: Story -> Todo, tabular report

Template Loading

Templates: story_template.md , task_template_implementation.md

Loading Logic:

• Check if docs/templates/{template}.md exists in target project

• 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)

• 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

• Tools config: shared/references/tools_config_guide.md

• Storage mode operations: shared/references/storage_mode_detection.md

• AC validation rules: shared/references/ac_validation_rules.md

• Plan mode behavior: shared/references/plan_mode_pattern.md

• 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/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/dependency_validation.md (criteria #18-#19/#19b)

• references/risk_validation.md (criterion #20)

• references/traceability_validation.md (criteria #16-#17)

• references/domain_patterns.md (pattern registry for ln-002 delegation)

• references/penalty_points.md (penalty system details)

• Prevention checklist: shared/references/creation_quality_checklist.md (creator-facing mapping of 22 criteria)

• Linear integration: ../shared/templates/linear_integration.md

• MANDATORY READ: shared/references/research_tool_fallback.md

Version: 7.0.0 Last Updated: 2026-02-03