ln-402-task-reviewer

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

类型： L3 Worker 类别： 4XX 执行

任务审查

每次任务执行后都必须进行。 审查“待审查”中的单个任务，并决定将其标记为“已完成”还是“待返工”，同时立即修复或提供明确的返工说明。

此技能不是可选项。 每个已执行的任务都必须立即接受审查。没有例外，不得批量处理，也不得跳过。

目的与范围

• 解析任务 ID（依据输入解析链）；通过配置的跟踪器提供方（getTask、getStory）分别加载完整任务及其父 Story。
• 检查架构、正确性、配置规范、文档和测试。
• 对于测试任务，依据规划器模板验证基于风险的限制和优先级（≤15）。
• 仅更新此任务：接受（“已完成”），或退回（“待返工”），并给出明确原因和符合最佳实践的修复建议。

输入

输入	必填	来源	描述
taskId	是	args、父 Story、kanban、用户	要审查的任务

解析： 任务解析链。 状态筛选： 待审查

阶段 0：工具配置

必须读取： 加载 references/environment_state_contract.md、references/storage_mode_detection.md 和 references/input_resolution_pattern.md

提取：task_provider = 任务管理 -> 提供方（linear | github | file）。操作须与提供方无关；仅在执行跟踪器 I/O 时加载所选提供方的传输参考。

任务存储模式

此技能使用的跟踪器操作：getTask、getStory、updateStatus（已完成 | 待返工）、addComment、createTask（用于 [BUG] 副作用任务）。

模式检测

启动时检测运行模式：

规划模式已启用：

• 步骤 1-3：解析任务并加载上下文（只读，可在规划模式下执行）
• 生成审查计划（文件、检查项）→ 写入计划文件
• 调用 ExitPlanMode → 停止。不要执行审查。
• 步骤 4-9：获批后 → 执行完整审查

普通模式：

• 步骤 1-9：按标准工作流执行，不暂停

规划模式支持

条件读取：仅在规划模式启用时加载 references/plan_mode_pattern.md 中的 Workflow A。 工具策略：遵循宿主 AGENTS.md 中的 MCP 偏好；仅当宿主策略缺失或 MCP 行为不明确时，才加载 references/mcp_tool_preferences.md 和 references/mcp_integration_patterns.md。

重要：在规划模式下，计划文件 = 审查计划（将要检查的内容）。绝不要将审查发现或结论写入计划文件。

审查计划格式：

REVIEW PLAN for Task {ID}: {Title}

| Field | Value |
|-------|-------|
| Task | {ID}: {Title} |
| Status | {To Review} |
| Type | {impl/test/refactor} |
| Story | {Parent ID}: {Parent Title} |

Files to review:
- {file1} (deliverable)
- {file2} (affected component)

| # | Check | Will Verify |
|---|-------|-------------|
| 1 | Approach | Technical Approach alignment |
| 2 | Clean Code | No dead code, no backward compat shims |
| 3 | Config | No hardcoded creds/URLs |
| 4 | Errors | try/catch on external calls |
| 5 | Logging | ERROR/INFO/DEBUG levels |
| 6 | Comments | WHY not WHAT, docstrings |
| 7 | Naming | Project conventions |
| 8 | Docs | API/env/README updates |
| 9 | Tests | Updated/risk-based limits |
| 10 | AC | 4 criteria validation |
| 11 | Side-effects | Pre-existing bugs in touched files |
| 12 | Destructive ops | Safety guards from destructive_operation_safety.md (loaded in step 4) |
| 13 | Algorithm correctness | Loop invariants, collection keys, unbounded ops, shared state leaks |
| 14 | Event channels | Channel name consistency in diff |
| 15 | CI Checks | lint/typecheck pass per ci_tool_detection.md |

Expected output: Verdict (`Done | To Rework`) + Issues + Fix actions

使用 TodoWrite 跟踪进度

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

规则：

1. 在步骤 1 开始前立即创建待办事项
2. 每个工作流步骤 = 单独的待办事项；包含多项检查的步骤须添加子项
3. 开始步骤前标记为 in_progress，完成后标记为 completed

待办模板（约 11 项）：

Step 1: Resolve taskId
  - Resolve via args / Story context / kanban / AskUserQuestion (To Review filter)

Step 2: Load Task
  - Load task by ID, detect type

Step 3: Read Context
  - Load full task + parent Story + affected components

Step 3b: Goal Articulation Gate
  - State what specific quality question this review must answer (<=25 tokens each)

Step 4: Review Checks
  - Verify approach alignment with Story Technical Approach
  - Check clean code: no dead code, no backward compat shims
  - Cross-file DRY: Grep src/ for new function/class names (count mode). 3+ similar → CONCERN
  - Check config hygiene, error handling, logging
  - Check comments, naming, docs updates
  - Verify tests updated/run (risk-based limits for test tasks)

Step 5: AC Validation
  - Validate implementation against 4 AC criteria

Step 6: Side-Effect Bug Detection
  - Scan for bugs outside task scope, create [BUG] tasks

Step 7: Decision
  - Apply minor fixes or set To Rework with guidance

Step 8: Mechanical Verification
  - Run lint/typecheck per ci_tool_detection.md (only if verdict=Done)

Step 9: Update & Commit
  - Set task status, update kanban, post review comment
  - If Done: leave branch changes uncommitted for downstream branch ownership rules

工作流（简要）

如果语义差异、克隆组、引用或审查影响范围很重要，优先使用 hex-graph。如果可用，读取本地代码/配置/脚本/测试时优先使用 hex-line。如果 MCP 不可用、不受支持或未建立索引，请继续使用内置的 Read/Grep/Glob/Bash，并在审查中记录回退情况，不要因此阻塞。

1. 解析 taskId： 按照指南运行任务解析链（状态筛选：[To Review]）。

2. 加载任务： 独立加载完整任务和父级 Story。检测类型（标签为 "tests" -> 测试任务，否则为实现/重构任务）。

3. 阅读上下文： 完整任务 + 父级 Story；加载受影响的组件/文档；如有 diff，则进行审查。 Hex MCP 加速： 如果图已建立索引，优先使用 analyze_changes(path=project_root, base_ref="HEAD~1") 获取语义风险快照；使用 changes(path="src/", compare_against="HEAD~1") 对结构性变更进行 AST 级 diff 审查。 3b) 目标关卡： 审查前，说明：(1) REAL GOAL：本次审查必须回答什么质量问题？(2) DONE：什么证据能够证明质量已达标？(3) NOT THE GOAL：表面化走过场的审查会是什么样？(4) INVARIANTS：存在哪些不明显的约束？仅当此关卡存在歧义或争议时，才加载 references/goal_articulation_gate.md。

4. 审查检查项：

   规格优先关卡： 快速预检 AC：对照实现检查任务 AC。如果有任何 AC 明显未满足（BLOCKER 级别）→ 立即标记为 To Rework，跳过其余质量检查。完整 AC 验证仍须在第 5 步执行。 必须阅读： 加载 references/clean_code_checklist.md、references/destructive_operation_safety.md

   • 目标验证（Recovery Paradox）： 如果执行者阐述了 REAL GOAL（可见于任务评论或实现中），验证它是否与 Story 的目标交付物一致。如果执行者将目标围绕次要事项表述（例如“实现端点”而非“支持用户导出数据”）→ CONCERN：GOAL-MISFRAME: executor goal targets secondary subject, may miss hidden constraints.
   • 蓝图完成情况（建议项）： 如果执行者的运行时数据可用（此任务对应的 .hex-skills/runtime-artifacts/runs/），加载 PHASE_3 蓝图以及执行者检查点中的 PHASE_6 blueprint_status。如果 completion_pct < 100，但未说明跳过项目的理由，或新增文件超过计划文件的 50%，但未说明理由，则标记为 CONCERN。如果运行时数据不可用，则检查执行者摘要中的 metadata.blueprint_status。这不是 BLOCKER。
   • 实施方案：diff 与 Story 中的 Technical Approach 一致。如果不同 → 在代码注释中记录理由。
   • 整洁代码： 按照清单验证全部 4 个类别。确保已完全移除被替换的实现。如果重构改变了 API，确保调用方已更新，旧签名已移除。
   • 跨文件 DRY： 对任务新建的每个函数/类/处理器，在 src/ 中 Grep 相似名称/模式（计数模式）。如果有 3 个或更多文件包含相似逻辑 → 添加 CONCERN：MNT-DRY-CROSS: {pattern} appears in {count} files — consider extracting to shared module. 这可以发现单任务审查遗漏的跨 Story 重复。
   • 优先使用跨文件 DRY（hex-graph）： 如果 hex-graph 已建立索引，使用 audit_workspace(path=scan_path, verbosity="minimal", limit=5, clone_member_limit=3) 并检查返回的 clones。仅当有界预览不足时才提高限制。筛选出至少有一个成员位于任务修改文件中的组。每个匹配项均添加 CONCERN：MNT-DRY-CROSS。如果 hex-graph 不可用，则使用上述 Grep 名称搜索方式。
   • 不得硬编码凭据/URL/魔法数字；配置应放在 env/config 中。
   • 破坏性操作防护：使用上文已加载的 destructive_operation_safety.md 中的代码级防护表。严重级别为 CRITICAL/HIGH → BLOCKER：SEC-DESTR-{ID}。严重级别为 MEDIUM → CONCERN：SEC-DESTR-{ID}。
   • 错误处理：所有外部调用（API、DB、文件 I/O）都必须用 try/catch 或等效方式包装。不得吞掉异常。遵循分层原则；复用现有组件。
   • 副作用范围：具有 3 个或更多副作用类别的叶子服务函数 → CONCERN：ARCH-AI-SEB。例外：编排器/协调器函数（导入 3 个或更多服务并按顺序委派）预期会有多个副作用类别——不要标记。
   • 接口诚实性：名称表示读取的函数（get_/find_/check_）若有写入副作用 → CONCERN：ARCH-AI-AH
   • 日志记录：错误使用 ERROR；认证/支付事件使用 INFO；调试数据使用 DEBUG。日志不得包含敏感数据。
   • 注释：说明 WHY，而非 WHAT；不得保留注释掉的代码；公共方法应有 docstring。
   • 命名：遵循项目现有惯例（检查 3 个或更多相似文件）。除领域术语外，不使用缩写。不得使用单字母变量（循环变量除外）。
   • 实体泄漏：不得从 API 端点直接返回 ORM 实体。使用 DTO/响应模型。（认证/支付场景为 BLOCKER，其他场景为 CONCERN）
   • 方法签名：公共方法不得使用布尔标志参数（应使用枚举/选项对象）；不使用 DTO 时，参数不得超过 5 个。（NIT）
   • 算法正确性（循环、集合、边界）： 循环中的 break/continue/return 是否能处理所有匹配项，而不只是第一个？字典/集合推导式是否能正确处理重复键（最后写入胜出可能导致数据丢失）？是否存在 list(query.all()) 或在用户控制的数据上运行且没有 LIMIT 的无限循环？是否存在会在请求间泄漏的可变共享状态（连接池 GUC、会话全局变量）？（如果会导致数据丢失/损坏，则为 BLOCKER；否则为 CONCERN）
   • 事件通道一致性（任务范围）： 当任务 diff 涉及事件相关代码（NOTIFY/LISTEN/emit/subscribe/publish/on）时，验证：(1) 发布者和订阅者的通道名称字符串是否匹配；(2) 如果通道名称是新的字符串字面量，则在 src/ 中 Grep 查找匹配的监听者/发布者对应项。不匹配 → CONCERN：ARCH-EVENT-MISMATCH: publisher '{pub_name}' has no matching subscriber。孤立项 → CONCERN：ARCH-EVENT-ORPHAN: subscriber '{sub_name}' has no matching publisher。
   • 简洁性标准（任务范围）： 在此处检查 MNT-KISS-SCOPE 和 MNT-YAGNI-SCOPE；仅在报告这些建议性 CONCERN 时，才加载 references/simplicity_criterion.md。
   • 代码效率（任务范围）： 从 diff 中抽查 2-3 个关键函数，检查是否存在不必要的中间步骤、明明有惯用写法却采用冗长模式，或框架已能处理却仍编写样板代码。如发现问题 -> CONCERN：MNT-EFF-SCOPE: {pattern} in {file}。仅当项目上下文不明确时，才加载 references/code_efficiency_criterion.md。
   • 前端审查（有条件）： 如果审查文件包含 .tsx/.vue/.svelte/.html/.css，加载 references/frontend_design_guide.md，并检查无障碍性、组合方式、排版、文案、动效和设计系统遵循情况。
   • 文档：如果公共 API 有变更 → 更新 API 文档。如果新增 env var → 更新 .env.example。如果引入新概念 → 更新 README/架构文档。
   • 更新/运行测试：对于实现/重构任务，确保相应测试已调整；对于测试任务，根据 planner 模板验证基于风险的限制和优先级（≤15）。

5. AC 验证（实现任务必须执行）： 必须阅读： 加载 references/ac_validation_checklist.md。根据 4 项标准验证实现：

   • AC 完整性： 覆盖所有 AC 场景（正常路径 + 错误 + 边界情况）。
   • AC 明确性： 满足精确要求（HTTP 状态码 200/401/403、耗时 <200ms、确切消息）。
   • 任务依赖： 任务 N 仅使用任务 1 到 N-1（不得依赖后续的 N+1、N+2）。
   • 数据库创建： 任务只创建 Story 范围内的表（不得一次性创建整个架构）。 如果任何标准不满足 → 标记为 To Rework，并根据清单提供具体指导。

6. 副作用 Bug 检测（必须执行）： 审查受影响代码时，主动扫描与当前任务无关的 Bug/问题：

   • 被修改文件中已有的 Bug
   • 相邻代码中的错误模式
   • 相关组件中的安全问题
   • 不受支持的 API、过时的依赖
   • 调用方/被调用方函数中缺少错误处理 对于发现的每个副作用漏洞：
   • 在同一个 Story 中创建新任务：
     • 使用已配置的跟踪器提供方的 createTask 操作。传入 parentId = Story.id、标签 ["bug", "discovered-in-review"]、状态 Backlog，并根据严重程度设置优先级。
   • 标题：[BUG] {简短描述}
   • 描述：位置、问题、建议的修复方案
   • 标签：bug、discovered-in-review
   • 优先级：根据严重程度确定（安全问题 → 1 Urgent，逻辑问题 → 2 High，样式问题 → 4 Low）
   • 不得延后——立即创建任务；审核者要捕获执行者遗漏的问题

7. 决策（仅针对当前任务）：

   • 如果只有细微问题：应用小幅修复并设为 Done。
   • 如果仍有问题：设为 To Rework，并添加评论说明原因（引用最佳实践）及修复方法。
   • 副作用漏洞不会阻止当前任务设为 Done（它们是独立任务）。
   • 如果设为 Done： 保留未提交的分支更改，并移交已验收的任务状态，同时附上审核评论和摘要产物。

8. 机械验证（如果设为 Done）： 必须读取： 加载 references/ci_tool_detection.md 如果判定结果为 Done：

   • 按照 ci_tool_detection.md 中的发现层级检测 lint/typecheck 命令
   • 运行检测到的检查（超时按指南执行：lint 检查 2 分钟，typecheck 5 分钟） 必须读取： 加载 references/output_normalization.md
   • 如果有任何 FAIL → 按照 §1 规范化 → §2 去重 → §4 截断至 50 行的顺序处理输出 → 将判定结果改为 To Rework，并附上规范化后的输出
   • 如果未检测到工具 → 跳过并输出提示信息

9. 更新： 通过已配置的跟踪器提供方（updateStatus）设置任务状态；更新看板：如果为 Done → 从看板中移除任务（Done 分区仅跟踪 Stories，不跟踪单个任务）；如果为 To Rework → 将任务移至 To Rework 分区；添加包含发现和操作的审核评论。如果创建了副作用漏洞任务，请在评论中提及。

审核质量评分

背景： 量化的审核结果可使后续决策便于审计，并跟踪审核一致性。

公式： Quality Score = 100 - (20 × BLOCKER_count) - (10 × CONCERN_count) - (3 × NIT_count)

对步骤 3-5 中发现的每个问题进行分类：

类别	权重	示例
BLOCKER	-20	未满足验收标准（AC）、安全问题、缺少错误处理、方案错误
CONCERN	-10	模式欠佳、缺少文档、测试覆盖不足
NIT	-3	命名、样式、轻微清理

判定映射：

分数	判定结果	操作
90-100	Done	接受，并直接应用细微问题修复
70-89	Done（附注释）	接受，并记录待后续处理的问题
<70	To Rework	退回，并针对每个问题提供修复指导

注意： 副作用漏洞（步骤 5）不影响当前任务的质量评分——它们会成为独立的 [BUG] 任务。

关键规则

• 一次处理一个任务；副作用漏洞 → 独立的 [BUG] 任务（不扩大范围）。
• 质量门槛：设为 Done 前解决所有范围内的问题，或退回并提供明确的修复指导。
• 测试任务违规（限制/优先级 ≤15）→ To Rework。
• 编辑和评论中保留任务使用的语言（EN/RU）。
• 仅当判定结果为 Done 时运行机械检查（lint/typecheck）；To Rework 时跳过。

运行时摘要产物

必须读取： 加载 references/coordinator_summary_contract.md、references/worker_runtime_contract.md、references/task_worker_runtime_contract.md

共享契约：

• 输出 summary_kind=task-status
• 独立模式省略 runId 和 summaryArtifactPath
• 托管模式在 Worker 写入经过验证的审核结果前，传入 runId 和确切的 summaryArtifactPath

监控（2.1.98+）： 对预计耗时超过 30 秒的 lint/typecheck 命令，使用 Monitor。备用方案：Bash(run_in_background=true)。

完成定义

• 已完成步骤 1-9：任务已解决、上下文已加载、审查检查已通过、AC 已验证、已创建副作用缺陷、机械验证已通过、已应用决策。
• 如果为 Done：审查通过后从看板中移除任务。如果为 To Rework：将任务移至相应位置并提供修复指导。
• 已发布审查评论（发现的问题 + [BUG] 列表，如有）。
• 已将运行时摘要产物写入共享任务状态位置。

参考文件

• 环境状态： references/environment_state_contract.md
• 存储模式操作： references/storage_mode_detection.md
• [MANDATORY] 问题解决方法： references/problem_solving.md
• AC 验证规则： references/ac_validation_rules.md
• AC 验证清单：references/ac_validation_checklist.md（4 项标准：完整性、明确性、依赖关系、数据库创建）
• 整洁代码清单： references/clean_code_checklist.md
• CI 工具检测： references/ci_tool_detection.md
• 输出规范化： references/output_normalization.md
• 看板格式：docs/tasks/kanban_board.md

---

版本： 5.2.0 最后更新： 2026-03-24