ln-310-story-validator
Validates Stories/Tasks with GO/NO-GO verdict, Readiness Score (1-10), Penalty Points, and Anti-Hallucination verification. Auto-fixes to reach 0 points, delegates to ln-002 for docs. Use when reviewing Stories before execution or when user requests validation.
How do I install this agent skill?
npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-310-story-validatorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a sophisticated story and task validator designed to automate the review process for project management. It enforces industry standards (RFC, OWASP), calculates quality 'penalty points', and auto-fixes structural or compliance issues in stories and tasks. It operates within a trusted ecosystem of sibling skills and focuses on improving project security by removing hardcoded credentials and ensuring technical claims are verified.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · No issues
- Runlayerwarn
5/14 files flagged
What does this agent skill do?
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_progressbefore starting step,completedafter 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")
- IF
- 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.mdwith APPROVED marker- IF
task_provider=linear:save_issue({id, state: "Todo"})for Story + each Task - IF
task_provider=file:Edit**Status:**line toTodoin story.md + each task file
- IF
- Add validation summary comment:
- IF
task_provider=linear:create_comment({issueId, body})on Story - IF
task_provider=file:Writecomment todocs/tasks/epics/.../comments/{ISO-timestamp}.md - Content: Penalty Points table (Before -> After = 0), Auto-Fixes Applied, Documentation Created (via ln-002), Standards Compliance Evidence
- IF
- Display tabular output (Unicode box-drawing) to terminal
- Final: Total Penalty Points = 0
- Recommended next step:
ln-400-story-executorto 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"
- 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}.mdexists in target project - IF NOT EXISTS:
a. Create
docs/templates/directory if missing b. Copyshared/templates/{template}.md→docs/templates/{template}.mdc. Replace placeholders in the LOCAL copy:{{TEAM_ID}}→ fromdocs/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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/levnikolaevich/claude-code-skills/ln-310-story-validator">View ln-310-story-validator on skillZs</a>