plan-flow

Plan Flow

概要

次の場合にこのスキルを使用します。

• コードベース内の重複設計や冗長な設計を包括的に分析する必要がある場合。
• ファイル単位の手順を明示した詳細な TODO 計画が必要な場合。
• 厳密な実行証跡が求められる場合：1 つの手順を変更してテストし、その後で計画のステータスを更新します。

このスキルは、特定のリポジトリに依存しません。特定のリポジトリで行ったことだけでなく、分析と計画の方法を定めています。

基本ワークフロー（分析 -> 計画 -> 実行）

1. 対象範囲と制約を確認します。

• 対象のディレクトリ／モジュールと対象外の領域を確認します。
• 互換性要件、許容されるリスク、テストに関する期待事項を記録します。
• ベースライン（git status --short、現在のブランチ、既知の阻害要因）を記録します。

2. まず、構造化された冗長性分析を行います。

• アーキテクチャ上の中核要素を棚卸しします。
  • ドメインモデルとスキーマ
  • ファクトリー／レジストリのエントリーポイント
  • HTTP／ストレージ／キャッシュ／ロギングの抽象化
  • ルート／サービス／プロバイダーのアダプター
• 証拠に基づいて、重複／冗長の候補を特定します。
  • 同じ概念に対して、相反する定義が複数ある
  • 同じ責務を担う実装が並行して存在する
  • エクスポートされているものの、どこにも接続されていないモジュール
  • 可読性に影響を及ぼし続けているデッドコード／レガシー経路
• 各指摘について、次の内容を記録します。
  • 正確なファイルとシンボル
  • 呼び出し経路または使用状況の証拠
  • 変更した場合のリスク
• references/analysis-playbook.md を参照してください。

3. 分析結果に優先順位を付け、実行可能な計画にまとめます。

• 各指摘を影響度／工数／リスク／確信度で評価します。
• フェーズ（P0、P1、P2）ごとにまとめ、リスクが低く効果が明確な手順から順に進めます。
• references/plan-template.md を基に plan/<task>.md を作成または更新します。
• in_progress の手順は常に 1 つだけにします。
• ステータスには pending／in_progress／completed／blocked を使用します。
• references/risk-impact-scoring.md を参照してください。

4. 厳密な「実行・テスト・更新」のループで進めます。

• 現在の手順のみを実装し、記載されたファイルのみを変更します。
• 手順単位のテストをすぐに実行し、その後でプロジェクトの健全性チェックを行います。
• 次の手順に着手する前に、計画のステータスと実行ログを更新します。
• 失敗した場合は根本原因を記録し、続行する前に修正ループを実行します。

5. フェーズごと、または最後に検証します。

• フェーズごとのチェックマトリクスと、最終的な回帰テスト一式を実行します。
• 残存するリスク、先送りした作業、明示的なカバレッジの不足を報告します。

品質ゲート

• ファイル単位の証拠がない指摘を計画に含めてはいけません。
• テストコマンドの証拠がない手順を completed にしてはいけません。
• 計画のステータスとログを更新する前に、次の手順を開始してはいけません。
• 回帰テストを全面的に実施できない場合は、正確な理由と、代わりに実行する最も近いチェックを記録します。

リファレンスマップ

• references/analysis-playbook.md
  • 再現可能な証拠に基づいて、重複／冗長な設計を検出する方法。
• references/risk-impact-scoring.md
  • 指摘に優先順位を付け、フェーズと手順の順序を決める方法。
• references/plan-template.md
  • 分析表、手順テンプレート、ログ形式を含む再利用可能な計画のひな形。
• references/plan-accomplishments.md
  • 完了した実例 1 件（スタイルと粒度の参考用であり、必須の対象範囲ではありません）。

スクリプト

• scripts/redundancy_scan.sh <target_dir>
  • 重複するシンボル名、並行するファクトリー／ビルダー、レガシーコード／デッドコードの兆候を対象に、最初の簡易スキャンを実行します。
• scripts/findings_to_plan.py --target-dir src --output plan/<name>.md
  • スキャン結果を基に、スコアリングとフェーズ別の順序（P0/P1/P2）を含む実行計画のドラフトを作成します。
• scripts/plan_lint.py <plan/file.md>
  • 完了した手順について、計画の状態遷移、テストの証拠、実行ログの完全性を検証します。

起動の目安

次のような依頼があった場合に、このスキルを起動します。

• 「このライブラリにどのような重複設計／冗長設計があるか分析して」
• 「非常に包括的で詳細な TODO／実行計画を作成して」
• 「変更するたびにテストして、計画のステータスを更新して」
• 「追跡可能な形で、手順に沿って進めて」

実行ルール

• 大規模なリファクタリングよりも、小さく元に戻しやすい手順を優先します。
• 計画では、ファイルパス、シンボル、コマンドを具体的に記述します。
• 分析上の結論と、検証されていない仮定を混在させないでください。
• 新たな証拠が以前の仮定と矛盾する場合は、コーディングを始める前に計画を修正します。