review-plan

計画のレビュー

計画書作成スキルなどで作成された実装計画を、実行前にレビューします。

引数

• パス：レビューする計画ファイル（例：docs/plans/2025-01-15-auth-feature.md）

捏造防止（ゲート 0 — 他のすべてのゲートより先に実行）

あらゆる判定を下す前に、つまり不足を指摘したり、問題を提起したり、判定を割り当てたりする前に、このターンで読み取ったソースから引用した、評価対象の成果物そのものを正確に引用しなければなりません。

• 計画に関する指摘の場合：レビュー対象の計画のステップまたはセクションのテキストを、今あらためて読み込んだ計画ファイルから引用します（セッション中の以前の記憶ではなく）。引用元の見出しまたはステップ番号も示してください。
• 計画が参照するコードベースの要素（型、API、ファイル）に関する主張の場合：今あらためて読み込んだコードを、ファイル名:行番号とともに引用します。

成果物だけを真実の根拠とします。計画に何が書かれているかを、ブランチ名、作業ディレクトリ、周辺ファイル、記憶から推測してはなりません。頭の中の理解が今回あらためて読み込んだソースと異なる場合は、ソースを優先します。 同じターンで対象を引用せずに下した判定は無効です。判定を下す前に引用するか、判定を出してはいけません。

このゲートは、文脈によるプライミングを受けた LLM が、計画に書かれていない内容を自信満々に指摘するのを防ぐためにあります。以下のハードゲートより先に実行します。

ハードゲート（順番どおりに実行）

先に進んではいけません。各ステップは、条件が客観的に満たされた場合にのみ合格とします（成果物のパス、ツールの実行成功、またはラベル付きの記録があること。「頭の中で読んだ」は認められません）。

1. 計画ファイルにアクセス可能 — 合格：Path の読み込みに成功すること。成功しない場合は停止し、見つからないパスを報告します。合格：**Goal:**、**Architecture:**、**Tech Stack:** の出現箇所を引用または示せること、あるいはステップ 2 の前に指摘事項として「ヘッダーフィールド X がありません」と記録すること。
2. レビュー前にスキルを読み込む — **合格：**ステップ 2 の表で使用する各行について、対応するスキルを読み込んでいること（またはスタックに該当しないなどの理由を添えて、明示的に N/A と記録すること）。このゲートに合格するまで、ステップ 3 のレビューを開始してはいけません。
3. 5 件のレビューを記録 — **合格：**ラベル付きの成果物が 5 つあること（各レビュー観点につき 1 つ。貼り付けた出力、サブエージェントのトランスクリプト、保存したスニペットファイルのいずれか）。**合格：**5 件の 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：5 つのレビュー観点を実施する

以下の 5 つのレビュー観点をすべて実施します。エージェントがサブエージェントをサポートしている場合は、5 つを個別のサブエージェントとして並行して実行します。サポートしていない場合は、自分で順番に実施し、同じ 5 つのラベル付き出力を作成します。各レビューには、次の情報を渡します。

• プランの全文
• 検出された技術スタック
• ステップ 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 を通過するには、5 つのラベル付きレビュー出力がそろっている必要があります。5 つすべての観点が完了したら（サブエージェントによる並列実行、または順次実行）、統合レポートを作成します。

## 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:

[replacement content]

#### 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 つのレビュー観点をすべて実施します。エージェントがサブエージェントをサポートしている場合は並行して実施し、サポートしていない場合は順次実施します
• 各問題について Task:Step を参照します
• 重大度が Critical／Major の問題には、コピー可能な修正案を提示します
• ユーザーにプロンプトを表示する前にレビューを保存します（ハードゲート 4）
• プランを自動実行しないでください。必ずユーザーに選択を求めます
• 問題には 1、2、3…と連番を付けます