ln-310-story-validator

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:

1. Audit: Calculate penalty points for all 22 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-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:

1. Create todos IMMEDIATELY before Phase 1
2. Each phase step = separate todo item
3. 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):
  1. Structural (#1-#4) — Story/Tasks template compliance + AC completeness/specificity
  2. Standards (#5) — RFC/OWASP compliance FIRST (before YAGNI/KISS!)
  3. Solution (#6, #21) — Library versions, alternative solutions
  4. Workflow (#7-#13) — Test strategy, docs integration, size, cleanup, YAGNI, KISS, task order
  5. Quality (#14-#15) — Documentation complete, hardcoded values
  6. Dependencies (#18-#19/#19b) — Story/Task independence (no forward deps), parallel group validity
  7. Risk (#20) — Implementation risk analysis (after dependencies resolved, before traceability)
  8. Verification (#22) — AC verify methods exist for all task ACs (test/command/inspect)
  9. 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:

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

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"

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: Agent review (delegated to ln-311-agent-reviewer → apply accepted suggestions)
6. Phase 6: 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

• 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