plan-auditor

Plan Auditor

このスキルを使用して、既存の PlanWeave プランを監査します。デフォルトでは、指摘事項と修正順序を出力します。監査中に新しいプランをインポートしたり、ブロックを実行したり、状態を修復したり、パッケージを書き換えたりしないでください。

クイックスタート

1. 根拠となる情報源を確認します。ユーザーのリクエスト、PRD、スキーマ、設計ドキュメント、現在のコード、PlanWeave パッケージを確認してください。
2. project-graph.json がある場合は、すべてのキャンバスの manifest.json、ソースプロンプト、タスク／ブロックの定義、キャンバス構造、依存関係、検証結果、および利用可能な場合は planweave schema の出力とともに読み込みます。
3. タスクの網羅性を判断する前に、プランの主要な価値フローまたはライフサイクルフローを特定し、必須のフローカバレッジ表を埋めます。
4. プランを、実際の目標、データフローの網羅性、オブジェクトのライフサイクル、契約、実行順序、プロンプト、失敗時の経路、検証基準と照らし合わせます。
5. まず判定を報告します。PASS、NEEDS_REVISION、BLOCKED のいずれかを記載してください。
6. 指摘事項を重大度順に、根拠と具体的なプランの変更内容とともに列挙します。

プラン更新の境界

• 監査で必要なタスク、ブロック、エッジ、プロンプト、レビュー、または検証の更新箇所を示します。変更自体は適用しません。
• ユーザーが修正の適用を明示的に求めた場合は、まず監査を完了してから、Plan Package のセマンティック編集の境界に従います。CLI のワークスペースパスを解決し、修正に必要な project-graph.json、キャンバスの manifest.json、ソースプロンプトの Markdown のみを編集し、キャンバス単位の検証とプロジェクトの検証を実行してください。
• このスキルでは、実行時の state.json、results/、アクティブなキャンバスの選択、復旧トランザクション、実装成果物を編集しないでください。

必須の出力

1. 判定：PASS、NEEDS_REVISION、または BLOCKED。
2. 指摘事項より前にフローカバレッジ表を記載します。
3. 重大度別の指摘事項。
4. 推奨する修正順序。

フローカバレッジ表：

フロー	トリガー／入力	コア処理	外部依存関係	状態／ストレージ	インターフェース／利用者	出力／副作用	失敗時の経路	検証	ギャップ

各セルには、該当する場合、正確な PlanWeave のタスク／ブロック ID、プロンプト、参照ファイル、検証方法を記載してください。タスクの網羅性、プロンプトの網羅性、依存関係のエッジ、検証、実際の動作、または必須の失敗処理が不足している場合は、Gap: を使用してください。

監査チェックリスト

目標の網羅性

• プランを評価する前に、根拠となる目標を特定します。
• 主要な目標、要件、制約、リスクがすべて反映されているか確認します。
• 省略された要件、弱められた要件、誤って先送りされた要件を指摘します。
• ユーザーが明示的に範囲を限定していない限り、デモ用の一部実装を完全な納品として認めないでください。

データフローの網羅性

• このセクションは必須です。タスクリストの網羅性を判断する前に完了してください。
• プランの主要な価値フローまたはライフサイクルフローを特定します。フローとは、入力、判断、オブジェクト、ユーザー操作、外部イベント、またはスケジュールされたジョブがシステム内を移動し、観測可能な結果を生み出す経路です。
• 主要な各フローについて、該当する段階を追跡します。ソース／トリガー／入力、検証／正規化／解析、計画／判断／オーケストレーション、処理／変換／実行、外部依存関係／プロバイダー／モデル／ツール呼び出し、状態／永続化／キャッシュ／成果物ストレージ、契約／インターフェース／API／CLI／イベント／メッセージ、ユーザーまたは下流での利用、出力／副作用／成果物／レポート、エラー／再試行／キャンセル／復旧、検証／可観測性／受け入れの証拠を確認してください。
• 該当する各段階を、正確な PlanWeave のタスク／ブロック ID、プロンプト、参照ファイル、依存関係のエッジ、検証方法に対応付けます。
• 必須の段階にタスク、プロンプト、依存関係のエッジ、または検証がない場合、あるいは目標が実際の動作を求めているのにモック動作のみで網羅されている場合は、ギャップとして報告します。
• タスクの数が多くても、エンドツーエンドのフローが途切れている場合は、網羅されていると見なさないでください。

コアオブジェクトのライフサイクル

• UI／API／DB／ワーカーのタスクを確認する前に、プロジェクトのコアオブジェクトを特定します。
• 各オブジェクトについて、誰が作成するか、どの構造で定義されるか、どこで検証されるか、誰が変換するか、状態がどのように変化するか、保存されるか、誰が利用するか、どのような副作用が発生するか、最終出力が存在するか、失敗／再試行／ロールバック／手動介入にどう対応するかを追跡します。
• オブジェクトに生成元はあっても利用者がいない場合や、セットアップはあっても最終出力がない場合は、ギャップとして記録します。

コントラクトの一貫性

• スキーマ、型、API パラメーター、CLI フラグ、イベント、ファイル形式、プロンプトの入出力を確認します。
• 生成側と利用側で、同じフィールド、ステータス、セマンティクスを使用する必要があります。
• コントラクトを変更するタスクでは、必要に応じて呼び出し元、テスト、フィクスチャ、ドキュメント、マイグレーションも対象に含める必要があります。
• コントラクトの欠落を覆い隠すフォールバック／デフォルト／any／モックのみの経路にフラグを立てます。

実行グラフ

• タスク、ブロック、キャンバス、プロジェクトグラフのエッジ、依存関係のエッジが、実際の実行順序を表しているか確認します。
• 並列タスクは、依存関係の到達可能性、データフロー、コントラクトのタイミングのいずれにおいても互いに独立している必要があります。
• 並列タスク間で共有リソースが重複する場合は、ブロッキング要件ではない調整上の注意点として特定します。順序付けが必要な重複については、明示的な依存関係を必須とします。
• 異なるキャンバスが自動的に並列になるわけではありません。正式なプロジェクトグラフがある場合、キャンバスをまたぐ依存関係は project-graph.json に明示する必要があります。
• キャンバスレベルの依存関係は、プロジェクトグラフのキャンバスエッジで表す必要があります。キャンバスをまたぐタスクのブロッカーは、crossTaskEdges に明示する必要があります。
• 密集または反復する crossTaskEdges、タスクエッジで表したステージ全体の順序、キャンバスの順序と重複するタスクエッジは、キャンバス境界の欠陥として扱います。
• 密接に関連するタスクは同じキャンバスに移し、ステージ全体にわたる依存関係はキャンバスエッジにする必要があります。タスクの移動やキャンバスエッジでは不適切な理由が具体的にある場合に限り、疎で削減不能なブロッカーとしてのクロスタスクエッジを認めます。
• キャンバスの順序をプロジェクト全体／プロジェクトのプロンプト、README の文章、またはエージェントへの指示だけで表している計画にフラグを立てます。
• 順次実行するゲートは明示する必要があります。
• 単に件数を増やすために分割されたタスクや、境界をまたぎすぎるタスクにフラグを立てます。
• 各キャンバスは、明確なフェーズ、機能領域、または並列作業グループを表す必要があります。

タスクとレビューの粒度

• 適切なタスクは、検証可能な機能スライス、コントラクトスライス、またはライフサイクルフェーズに対応する必要があります。
• スケジュール調整のオーバーヘッドだけが増える小さなタスクは統合します。
• サブエージェントが無関係なレイヤーをまたぐことになるタスクや、検証を制御できなくなるタスクは分割します。
• 単純なドキュメント、設定、リスクの低い文言修正、局所的な修正には、通常レビューは不要です。
• レイヤー横断、コントラクト、データベース、プロバイダー、アーキテクチャ、セキュリティ、プライバシー、または高リスクの動作変更には、レビューゲートを設ける必要があります。

プロンプトの品質

• すべてのタスク／ブロックのプロンプトは、サブエージェントが推測せずに作業を開始できる内容にする必要があります。
• 目的、参照ファイルのパス、影響範囲、禁止事項、完了条件、検証方法を確認します。
• 計画がプロジェクト全体／プロジェクトのプロンプトに依存している場合、それらのプロンプトに必要な背景情報が含まれているか確認します。
• プロンプト配置の概要で、全体／プロジェクト／タスク／ブロックのどこが信頼できる情報源となるかを特定しているか確認します。
• 完了の判定方法を説明せず、「これを実装する」とだけ記したプロンプトにフラグを立てます。

実質的な完了

• 見せかけの完了を探します。例：実行時に使われないスキーマ、呼び出し元のないインターフェース、動作を伴わない UI、読み込まれない設定、実際のクライアントを持たないプロバイダー抽象化、利用者のいないキュー、存在しないファイルパス、実運用経路のないドライラン、実際の処理チェーンをカバーしないフィクスチャテストなどです。
• 複雑なブロックに、アーキテクチャの境界、テストの配置場所、設定／環境変数の扱い、該当する場合は README または .env.example の更新、実際のプロバイダーとモックのどちらを想定するかが含まれているか確認します。
• 計画では、モック、ドライラン、実運用経路、実際に生成される成果物を区別する必要があります。

失敗時の経路

• エラー、再試行、キャンセル、タイムアウト、権限、部分的な成功、外部サービスの停止、人によるレビューの失敗、復旧を確認します。
• 信頼性の高い実行やステートマシンに関する作業では、異常状態と復旧戦略を最後の仕上げとしてではなく、早い段階から含める必要があります。

検証基準

• 各ブロックに、検証可能な完了基準が必要です。
• 具体的なコマンド、テスト、出力成果物、観測可能な状態変化、またはエンドツーエンドのフローを優先します。
• 「ロジックが正しい」「実装済み」「使えそう」といった曖昧な基準は認めません。

アーキテクチャの品質

• レイヤーの境界、単一の信頼できる情報源、スキーマやルールの重複リスク、一時的なフォールバック、モックが製品化するリスク、テスト容易性、保守性を確認します。
• 明示的に求められていない限り、無関係なプロジェクトからコピーされたスキル、ブートストラップルール、プロンプトの慣習は指摘します。
• 基盤となるタスクが未完了の場合、UI やパッケージ化の大規模なレイヤーを時期尚早に予定する計画は指摘します。

PlanWeave の実行可能性

• PlanWeave が実際に計画を実行できるか確認します。プロンプトが存在すること、ブロックを割り当てられること、依存関係が解除されること、レビューを提出できること、プロンプトのソースを編集できること、キャンバスの順序が明確であることを確認します。
• 正式な複数キャンバスの計画では、project-graph.json が存在すること、すべてのキャンバスが既存のパッケージを参照していること、すべてのタスク間参照が実在するタスクに解決されること、キャンバス間およびタスク間に依存関係の循環がないことを確認します。
• 単一キャンバスの manifest.json の意味がそのキャンバス内にとどまっていることを確認します。キャンバスをまたぐ依存関係の適用を、ローカルマニフェストやプロンプトの文面に隠してはなりません。
• 疑わしいプロジェクトグラフ、マニフェスト、状態、レイアウトの構造を、planweave schema project、planweave schema manifest、planweave schema state、planweave schema layout と照らし合わせます。
• 計画設計の欠陥と PlanWeave ツールチェーンの欠陥を分けます。

指摘事項の形式

各指摘事項で、次の形式を使用してください。

[P1] Short title
Evidence: path/ref/line or task/block/canvas id.
Impact: why this blocks or weakens execution.
Plan change: exact task, block, edge, prompt, review, or validation update needed.

最後に、推奨する修正の順序を記載してください。一般論だけで終わらせないでください。