ln-310-story-validator

路径： 文件路径（shared/、references/、../ln-*）均相对于技能仓库根目录。如果在当前工作目录中找不到，请定位此 SKILL.md 所在目录，并向上一级找到仓库根目录。

Story 验证技能

验证 Story/Task，并给出明确的 GO/NO-GO 判定、就绪度评分和反幻觉验证结果。

输入

输入	必需	来源	描述
storyId	是	args、git 分支、kanban、用户	要处理的 Story

解析： 遵循 shared/references/input_resolution_pattern.md 中的 Story 解析链。 状态筛选： Backlog

目的与范围

• 根据行业标准和项目模式验证 Story 及其子 Task
• 为违规项计算扣分，然后自动修复，直至扣分归零
• 委派给 ln-002-best-practices-researcher 创建文档（指南、手册、ADR、研究）
• 支持计划模式：显示审计结果，等待批准，然后修复
• 修复后批准 Story（Backlog -> Todo），并以表格汇总结果

使用时机

• 批准前审查 Story（Backlog -> Todo）
• 验证 Story 和 Task 的实现路径
• 确保符合标准、架构要求，且解决方案适用
• 优化或纠正拟议方案

扣分系统

目标： 对 Story/Task 质量进行量化评估。修复后目标为扣分 0 分。

严重程度	分值	描述
CRITICAL	10	违反 RFC/OWASP/安全要求
HIGH	5	库过时、架构问题
MEDIUM	3	违反最佳实践
LOW	1	结构/外观问题

工作流：

1. 审计：计算全部 22 项标准的扣分
2. 修复：自动修复并清零扣分
3. 报告：修复前总分 -> 修复后 0 分

模式检测

启动时检测运行模式：

计划模式已启用：

• 阶段 1-2：完整审计（发现 + 研究 + 扣分计算）
• 阶段 3：显示结果和修复计划 -> 等待用户批准
• 阶段 4-6：获批后 -> 执行修复

普通模式：

• 阶段 1-6：标准工作流，不中断
• 自动修复并批准

计划模式：使用 TodoWrite 跟踪进度

无论以何种模式运行，技能都必须创建详细的待办清单，跟踪所有阶段和步骤。

规则：

1. 在阶段 1 开始前立即创建待办事项
2. 每个阶段步骤 = 单独的待办事项
3. 开始步骤前标记为 in_progress，完成后标记为 completed

待办模板（约 21 项）：

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

工作流

阶段 0：工具配置

必须阅读： 加载 shared/references/tools_config_guide.md、shared/references/storage_mode_detection.md 和 shared/references/input_resolution_pattern.md

读取 docs/tools_config.md（如果缺失，则按照 tools_config_guide.md 进行初始化）。 提取：task_provider = Task Management → Provider（linear | file）。

后续所有阶段都使用 task_provider，根据 storage_mode_detection.md 选择操作。

阶段 1：发现与加载

步骤 1：解析 storyId（遵循 input_resolution_pattern.md）：

• 如果提供了 args → 使用 args
• 否则，如果 git 分支符合 feature/{id}-* → 提取 id
• 否则，如果 kanban 中 [Backlog] 下恰有 1 个 Story → 提出建议
• 否则 → AskUserQuestion：显示 kanban 中筛选为 [Backlog] 的 Story

步骤 2：加载配置与元数据

• 自动发现配置：团队 ID（docs/tasks/kanban_board.md）、项目文档（CLAUDE.md）、从 Story.project 获取的 Epic
• 仅加载元数据：Story ID/标题/状态/标签，子 Task 的 ID/标题/状态/标签
  • 如果 task_provider = linear：get_issue(storyId) + list_issues(parentId=storyId)
  • 如果 task_provider = file：Read story.md + Glob("docs/tasks/epics/*/stories/*/tasks/*.md")
• 预期有 1-8 个实现 Task；记录 parentId 以便筛选
• 原因：保持加载内容精简；完整描述将在阶段 2 加载

第 2 阶段：研究与审计

**必须阅读：**加载 references/phase2_research_audit.md，了解完整的研究与审计流程：

• 从 Story/Tasks 中提取领域信息
• 将文档工作委派给 ln-002（指南/手册/ADR）
• MCP 研究（通过 Ref + Context7 查阅 RFC/OWASP/库版本）
• 反幻觉验证（基于证据的声明）
• 扣分计算（22 项标准，参见同一文件中的自动修复操作参考）

每个 Story 都必须执行，无一例外。

第 3 阶段：审计结果与修复计划

展示审计结果：

• 扣分表（标准、严重程度、分值、说明）
• 总计：X 分
• 修复计划：列出每项标准对应的修复措施

模式处理：

• **如果是计划模式：**展示结果 + “经你批准后，将应用更改” -> 等待
• **否则（正常模式）：**立即进入第 4 阶段

第 4 阶段：自动修复

立即修复全部 22 项标准。

• 执行顺序（8 组）：
  1. 结构（#1-#4） — Story/Tasks 模板合规性 + AC 完整性/具体性
  2. 标准（#5） — 首先确保符合 RFC/OWASP（先于 YAGNI/KISS！）
  3. 解决方案（#6、#21） — 库版本、替代解决方案
  4. 工作流（#7-#13） — 测试策略、文档集成、规模、清理、YAGNI、KISS、任务顺序
  5. 质量（#14-#15） — 文档完整性、硬编码值
  6. 依赖项（#18-#19/#19b） — Story/Task 独立性（无前向依赖）、并行组有效性
  7. 风险（#20） — 实施风险分析（依赖项解决后、可追溯性检查前）
  8. 验证（#22） — 所有任务 AC 都有对应的验证方法（测试/命令/检查）
  9. 可追溯性（#16-#17） — Story-Task 对齐、AC 覆盖质量（最后执行，在所有修复完成后）
• 以下方的自动修复操作表为权威检查清单
• 修复时逐项清除扣分
• 必须保留 Test Strategy 部分，但内容留空（测试由单独流程处理）

第 5 阶段：Agent 审查（必须执行——不得跳过）

**必须执行的步骤：**无论第 4 阶段结果如何，都必须执行此阶段。跳过 Agent 审查属于违反工作流。如果 Agent 不可用，ln-311 会返回 SKIPPED——可以接受。但必须调用。

调用 Skill(skill="ln-311-agent-reviewer", args="{storyId}")。

• ln-311 从 Linear 获取 Story/Task 参考信息，构建包含参考信息的提示词，并行运行 Agent，将提示词和结果保存到 .agent-review/{agent}/。
• 如果判定结果为 SUGGESTIONS → 将已接受的建议应用到 Story/Tasks 文本中。
• 如果判定结果为 SKIPPED（没有 Agent 或全部失败） → 不作更改，进入第 6 阶段。
• **展示：**ln-311 输出中的 Agent 统计信息："Agent Review: {agent_stats summary}"

第 6 阶段：批准并通知

• 将 Story 和所有 Task 设为 Todo；使用 APPROVED 标记更新 kanban_board.md
  • 如果 task_provider = linear：对 Story 和每个 Task 调用 save_issue({id, state: "Todo"})
  • 如果 task_provider = file：在 story.md 和每个任务文件中，将 **Status:** 行改为 Todo
• 添加验证摘要评论：
  • 如果 task_provider = linear：在 Story 上调用 create_comment({issueId, body})
  • 如果 task_provider = file：将评论写入 docs/tasks/epics/.../comments/{ISO-timestamp}.md
  • 内容：扣分表（修复前 -> 修复后 = 0）、已应用的自动修复、创建的文档（通过 ln-002）、标准合规性证据
• 在终端显示表格输出（使用 Unicode 方框绘制字符）
• 最终结果：总扣分 = 0
• **建议的下一步：**使用 ln-400-story-executor 开始执行 Story

自动修复操作参考

必须阅读： 加载 references/phase2_research_audit.md，查看完整的 21 项标准表，其中包括：

• 结构（#1-#4）：故事/任务模板合规性
• 标准（#5）：RFC/OWASP 合规性
• 解决方案（#6、#21）：库版本、替代方案
• 工作流（#7-#13）：测试策略、文档、规模、YAGNI/KISS、任务顺序
• 质量（#14-#15）：文档、硬编码值
• 可追溯性（#16-#17）：故事-任务对齐、验收标准覆盖
• 依赖项（#18-#19/#19b）：无前置依赖
• 风险（#20）：实现风险分析

最高罚分： 88 分（22 项标准的总和；#20 上限为 15 分）

最终评估模型

应用所有修复后的输出：

指标	值	含义
关卡	GO / NO-GO	执行就绪度的最终判定
就绪度评分	1-10	质量可信度等级
罚分	0（修复后）	验证完整性
反幻觉	VERIFIED / FLAGGED	技术声明已验证
验收标准覆盖率	100% (N/N)	所有验收标准均已映射到任务

就绪度评分计算

Readiness Score = 10 - (Penalty Points / 5)

修复前后诊断： Phase 3 计算初始罚分和就绪度评分（修复前）。Phase 4 自动修复将罚分降至 0，就绪度评分达到 10（修复后）。为确保透明度，最终评估会报告这两个值。

关卡	条件
GO	Phase 4 后罚分 = 0（就绪度评分 = 10）
NO-GO	任何标准被标记为无法修复（见关键规则）

反幻觉验证

验证技术声明是否有证据支持：

声明类型	验证方式
RFC/标准引用	MCP Ref 搜索确认其存在
库版本	Context7 查询确认版本
安全要求	OWASP/CWE 引用存在
性能声明	基准测试/文档引用

状态： VERIFIED（所有声明均有来源）或 FLAGGED（列出未验证的声明）

任务-验收标准覆盖矩阵

输出明确的映射关系：

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

覆盖率： {covered}/{total} 个验收标准（目标：100%）

自审协议（强制）

在进入 Phase 6 之前，使用具体证据（文档路径、MCP 结果、Linear 更新）确认自动修复操作中的全部 22 项标准（#1-#22）均已通过。

关键规则

• 在进入 Phase 6 之前，必须使用具体证据（文档路径、MCP 结果、Linear 更新）验证全部 22 项标准（自审协议）
• 修复执行顺序严格固定：结构 -> 标准 -> 解决方案 -> 工作流 -> 质量 -> 依赖项 -> 风险 -> 可追溯性（标准先于 YAGNI/KISS）
• 罚分 > 0 时绝不批准；所有违规项都必须自动修复至 0。如果某项标准无法自动修复（例如，MCP Ref 不可用、存在外部依赖），则标记为 FLAGGED 并说明原因——罚分保留，关卡 = NO-GO，用户必须手动解决
• 测试策略部分必须存在，但保持空白（测试由其他技能单独处理）
• 在计划模式下，必须在 Phase 3 后停止，并等待用户批准后再应用任何修复

完成定义

• 已完成 Phase 1-6：已加载元数据、已完成研究、已计算罚分、已应用修复、已完成 Agent 审核、故事已批准。
• 罚分 = 0（已修复全部 22 项标准）。就绪度评分 ≥ 5。
• 反幻觉：VERIFIED（所有声明均通过 MCP 找到来源）。
• 验收标准覆盖率：100%（每项验收标准均映射到 ≥1 个任务）。
• Agent 审核：已调用 ln-311；已汇总、验证并应用建议（如果没有 Agent，则标记为 SKIPPED）。
• 已将故事/任务设为 Todo；已更新看板；已发布包含最终评估的 Linear 评论。

示例工作流

故事：“创建带速率限制的用户管理 API”

1. **阶段 1：**加载元数据（5 个任务，状态为 Backlog）
2. 阶段 2：
   • 领域提取：REST API、速率限制
   • 委派 ln-002：创建 Guide-05（REST 模式）、Guide-06（速率限制）
   • MCP Ref：符合 RFC 7231、OWASP API Security
   • Context7：Express v4.19（当前为 v4.17）
   • 处罚分：总计 18 分（版本=5、缺少文档=5、结构=3、标准=5）
3. 阶段 3：
   • 显示处罚分表格
   • 如果处于计划模式：“发现 18 个处罚分。修复计划已就绪。是否批准？”
4. 阶段 4：
   • 修复 #6：将 Express v4.17 更新为 v4.19
   • 修复 #5：添加符合 RFC 7231 的说明
   • 修复 #13：添加 Guide-05、Guide-06 引用
   • 修复 #17：ln-002 已创建文档
   • 已应用所有修复，处罚分 = 0
5. **阶段 5：**Agent 审核（委派给 ln-311-agent-reviewer → 应用已接受的建议）
6. **阶段 6：**故事 -> Todo，表格报告

模板加载

模板：story_template.md、task_template_implementation.md

加载逻辑：

1. 检查目标项目中是否存在 docs/templates/{template}.md
2. 如果不存在： a. 如果缺少 docs/templates/ 目录，则创建该目录 b. 复制 shared/templates/{template}.md → docs/templates/{template}.md c. 在本地副本中替换占位符：
   • {{TEAM_ID}} → 来自 docs/tasks/kanban_board.md
   • {{DOCS_PATH}} → “docs”（标准值）
3. 在所有验证操作中使用本地副本（docs/templates/{template}.md）

**理由：**首次使用时将模板复制到目标项目，确保：

• 项目独立性（不依赖 skills 仓库）
• 可自定义（项目可以修改本地模板）
• 占位符在复制时一次性替换

参考文件

• 工具配置：shared/references/tools_config_guide.md
• 存储模式操作：shared/references/storage_mode_detection.md
• AC 验证规则：shared/references/ac_validation_rules.md
• 计划模式行为：shared/references/plan_mode_pattern.md
• 最终评估：references/readiness_scoring.md（GO/NO-GO 规则、Readiness Score 计算）
• 模板（集中管理）：shared/templates/story_template.md、shared/templates/task_template_implementation.md
• 本地副本：docs/templates/（位于目标项目中）
• 验证检查清单（渐进式披露）：
  • references/structural_validation.md（标准 #1-#4）
  • references/standards_validation.md（标准 #5）
  • references/solution_validation.md（标准 #6）
  • references/workflow_validation.md（标准 #7-#13）
  • references/quality_validation.md（标准 #14-#15）
  • references/dependency_validation.md（标准 #18-#19/#19b）
  • references/risk_validation.md（标准 #20）
  • references/traceability_validation.md（标准 #16-#17）
  • references/domain_patterns.md（用于 ln-002 委派的模式注册表）
  • references/penalty_points.md（处罚分系统详情）
• 预防检查清单：shared/references/creation_quality_checklist.md（面向创建者的 22 项标准映射）
• Linear 集成：../shared/templates/linear_integration.md
• 必须阅读：shared/references/research_tool_fallback.md

---

**版本：**7.0.0 **最后更新：**2026-02-03