review-plan

评审计划

在执行前评审实施计划（例如由编写计划的技能生成的计划）。

参数

• 路径：要评审的计划文件（例如，docs/plans/2025-01-15-auth-feature.md）

防止臆造（关卡 0 — 在其他所有关卡之前运行）

在给出任何结论之前——标记缺口、提出问题或判定结论——你 MUST 引用本轮中读取的来源，准确复述你正在评判的内容：

• 对于计划中的发现：引用刚刚从计划文件中读取的、正在评审的计划步骤或章节文本（不得凭记忆引用本轮之前会话中的内容），并注明其所属标题或步骤编号。
• 对于有关计划涉及的代码库的说法（计划引用的类型、API 或文件）：引用刚刚读取的文件:行号及相关代码。

该工件是唯一可信来源。绝不要根据分支名称、工作目录、周边文件或记忆推断计划内容。如果你对内容的理解与刚刚读取的来源不同，以来源为准。未在本轮中复述目标内容就给出的结论无效——先复述内容，否则不要给出结论。

设立此关卡是因为 LLM 在上下文诱导下会自信地指出计划中并不存在的内容。此关卡在以下硬性关卡之前运行。

硬性关卡（按顺序执行）

不得跳过步骤；只有客观满足条件（工件路径、工具成功或带标签的记录）时，步骤才算通过，不能仅凭“我在脑中读过”。

1. 可访问计划文件 — **通过：**成功读取Path；如果读取失败，停止并报告缺失路径。**通过：**可以引用或指出**Goal:**、**Architecture:**和**Tech Stack:**出现的位置，或者在步骤 2 之前将“缺少字段 X”记录为一项发现。
2. 评审前加载技能 — **通过：**对于步骤 2 表格中将要参考的每一行，都已加载相应技能（或者明确记录N/A及原因，例如未使用该技术栈）。在此关卡通过前，不要开始步骤 3 的评审。
3. 记录五项评审 — **通过：**已有五份带标签的工件（每种评审视角各一份）：粘贴的输出、子 Agent 对话记录或已保存的片段文件。**通过：**每个 INVESTIGATE/CHECK/VERIFY 提示词都有对应的回复块，且位于步骤 4 之前。
4. 在用户提示前将评审文件写入磁盘 — 通过：[plan-dir]/[plan-basename]-review.md路径下的文件已存在；**通过：**成功读取该路径。只有此后才可在步骤 5 中运行“后续步骤”/选项提示。

步骤 1：读取并解析计划

读取计划文件并提取：

1. 标题字段：

   • **Goal:** — 功能描述
   • **Architecture:** — 方案概要
   • **Tech Stack:** — 使用的技术

2. 通过文件模式验证：

   • .py文件 → Python
   • .ts、.tsx文件 → TypeScript
   • .go文件 → Go
   • pytest命令 → pytest
   • vitest、jest命令 → JavaScript/TypeScript 测试
   • go test命令 → Go 测试

步骤 2：加载技能

加载所有适用的技能（例如 python-code-review 技能）。

根据检测到的技术栈，加载相关技能：

检测到的技术栈	技能
Python	python-code-review
FastAPI	fastapi-code-review
SQLAlchemy	sqlalchemy-code-review
PostgreSQL	postgres-code-review
pytest	pytest-code-review
React Router	react-router-code-review
React Flow	react-flow-code-review
shadcn/ui	shadcn-code-review
vitest	vitest-testing
Go	go-code-review
BubbleTea	bubbletea-code-review

步骤 3：运行五个审查维度

运行以下全部五个审查维度。如果 Agent 支持子 Agent，则将五个维度分别作为独立子 Agent 并行分派；否则，按顺序自行完成，并生成同样的五项带标签输出。每项审查都需接收：

• 完整计划内容
• 检测到的技术栈
• 步骤 2 中的相关技能内容

维度 1：并行化分析

Analyze whether this implementation plan can be executed by parallel subagents.

INVESTIGATE:
1. Which tasks can run in parallel (no dependencies between them)?
2. Which tasks must be sequential (Task B depends on Task A output)?
3. Are there any circular dependencies or blocking issues?
4. What is the critical path?

Return:
- Recommended batch structure for parallel execution
- Maximum concurrent agents
- Any blocking issues that prevent parallelization

维度 2：TDD 与过度设计检查

Verify TDD discipline in this implementation plan.

CHECK each task for:
1. Tests written BEFORE implementation (RED phase)
2. Step to run test and verify it fails
3. Minimal implementation to make test pass (GREEN phase)
4. Tests focus on behavior, not implementation details

LOOK FOR over-engineering:
- Excessive mocking (testing implementation vs behavior)
- Too many abstraction layers
- Defensive code for impossible scenarios
- Premature optimization

Return: TDD adherence assessment and over-engineering concerns.

维度 3：类型与 API 验证

Verify types and APIs in the plan match the actual codebase.

SEARCH the codebase for:
1. All types referenced in the plan's code blocks
2. Existing type definitions
3. API endpoint contracts (request/response shapes)
4. Import paths

VERIFY:
1. All properties referenced exist in the types
2. Enum values match between plan and codebase
3. Import paths are correct
4. No type mismatches

Return: List of mismatches with file:line references.

维度 4：库的最佳实践

Verify library usage in this plan follows best practices.

For each library referenced:
1. Are function signatures correct for current versions?
2. Are there deprecated APIs being used?
3. Does usage follow library documentation?
4. Are installation commands correct?

Check against loaded skills for technology-specific guidance.

Return: Incorrect API usage with recommendations.

维度 5：安全性与边缘情况

Check for security gaps and missing error handling.

VERIFY:
1. Input validation at system boundaries
2. Error handling in API/DB operations
3. Auth/authz checks where needed
4. Edge cases are handled

Return: Security gaps and missing error handling.

步骤 4：综合报告

关卡： 硬性关卡 3 必须通过（存在五项带标签的审查输出）。五个维度全部完成后（通过并行子 Agent 或顺序审查），创建综合报告：

## Plan Review: [Feature Name from plan]

**Plan:** `[path to plan file]`
**Tech Stack:** [Detected technologies]

### Summary Table

| Criterion | Status | Notes |
|-----------|--------|-------|
| Parallelization | ✅ GOOD / ⚠️ ISSUES | [Brief note] |
| TDD Adherence | ✅ GOOD / ⚠️ ISSUES | [Brief note] |
| Type/API Match | ✅ GOOD / ⚠️ ISSUES | [Brief note] |
| Library Practices | ✅ GOOD / ⚠️ ISSUES | [Brief note] |
| Security/Edge Cases | ✅ GOOD / ⚠️ ISSUES | [Brief note] |

### Issues Found

#### Critical (Must Fix Before Execution)

1. [Task N, Step M] ISSUE_CODE
   - Issue: What's wrong
   - Why: Impact if not fixed
   - Fix: Specific change
   - Suggested edit:

[替换内容]

#### Major (Should Fix)

2. [Task N] ISSUE_CODE
- Issue: ...
- Why: ...
- Fix: ...

#### Minor (Nice to Have)

3. [Task N] ISSUE_CODE
- Issue: ...
- Fix: ...

### Verdict

**Ready to execute?** Yes | With fixes (1-N) | No

**Reasoning:** [1-2 sentence assessment]

步骤 5：保存审查结果和提示词

关卡： 写入审查文件后，在提示用户之前，须满足硬性关卡 4（成功读取审查路径）。

将审查结果保存到与计划相同的目录：

• 计划：docs/plans/2025-01-15-feature.md
• 审查：docs/plans/2025-01-15-feature-review.md

审查文件标题：

# Plan Review: [Feature Name]

> **To apply fixes:** Open new session, run:
> `Read this file, then apply the suggested fixes to [plan path]`

**Reviewed:** [Current date/time]
**Verdict:** [Yes | With fixes (1-N) | No]

---

提示用户：

---

## Next Steps

**Review saved to:** `[review file path]`

**Options:**

1. **Apply fixes now** - Edit the plan file to address issues
2. **Save & fix later** - Open new session to apply fixes
3. **Proceed anyway** - Execute plan despite issues (not recommended for Critical)

Which option?

规则

• 在步骤 3 之前满足硬性关卡 1–2；在步骤 4 之前满足硬性关卡 3；在步骤 5 的选项提示之前满足硬性关卡 4
• 在运行审查维度之前加载技能（硬性关卡 2）
• 运行全部 5 个审查维度——Agent 支持子 Agent 时并行运行，否则按顺序运行
• 每个问题都注明对应的任务步骤
• 为严重/主要问题提供可复制的建议修改内容
• 在提示用户之前保存审查结果（硬性关卡 4）
• 绝不自动执行计划；必须由用户选择
• 按顺序为问题编号（1、2、3……）