analyze-project

/analyze-project — 根本原因アナリストワークフロー

~/.gemini/antigravity/brain/ 内の AI 支援コーディングセッションを分析し、何が起きたかだけでなく、なぜ起きたか、誰/何が原因か、次回何を変えるべきかを説明するレポートを作成します。

目標

各セッションについて、以下を判定します:

1. 最初の依頼から最終的に実行された作業までに何が変わったか
2. 主な原因が次のどれであったか:
   • ユーザー/仕様
   • エージェント
   • リポジトリ/コードベース
   • 検証/テスト
   • 正当なタスクの複雑さ
3. 冒頭のプロンプトが十分であったか
4. どのファイル/サブシステムが繰り返し苦戦と相関しているか
5. どのような変更が今後のセッションを最も改善するか

使用する場面

• AI 支援コーディングセッション、特にスコープのドリフトや繰り返しの手戻りが発生した場合のポストモーテムが必要なとき。
• ユーザー/仕様の問題と、エージェントのミス、リポジトリの摩擦、検証の不足を切り分ける根本原因分析を行いたいとき。
• 今後のプロンプト、リポジトリの健全性、デリバリーワークフローの改善に向けた、証拠に基づく推奨事項が必要なとき。

グローバルルール

• .resolved.N のカウントはイテレーションのシグナルとして扱い、失敗の証明とはみなさない
• 人間が追加したスコープ、発見により必要となったスコープ、エージェントが導入したスコープを分離する
• エージェントのエラーとリポジトリの摩擦を分離する
• すべての診断には証拠と信頼度を含める
• 信頼度レベル:
  • 高 = 直接的な成果物/タイムスタンプの証拠
  • 中 = 複数の裏付けとなるシグナル
  • 低 = もっともらしい推測であり、直接証明されていない
• 証拠の優先順位:
  • 成果物の内容 > タイムスタンプ > メタデータの要約 > 推測
• 証拠が弱い場合は、その旨を明記する

---

ステップ 0.5: セッション意図の分類

目的 + 成果物から、セッションの主な意図を分類します:

• DELIVERY
• DEBUGGING
• REFACTOR
• RESEARCH
• EXPLORATION
• AUDIT_ANALYSIS

記録:

• session_intent
• session_intent_confidence

意図を使用して、重大度と手戻りの形を文脈化します。 探索的セッションやリサーチセッションを、狭いデリバリーセッションと同じ基準で判断しないでください。

---

ステップ 1: 会話の検出

1. システムコンテキストから利用可能な会話の要約を読み取る
2. ユーザーの Antigravity brain/ ディレクトリ内の会話フォルダを一覧表示する
3. 以下を含む会話インデックスを構築する:
   • conversation_id
   • title
   • objective
   • created
   • last_modified
4. ユーザーがキーワード/パスを指定した場合は、一致する会話に絞り込む。それ以外の場合はすべてを分析する

出力: 分析対象の会話のインデックス付きリスト。

---

ステップ 2: セッション証拠の抽出

各会話について、存在する場合は以下を読み取ります:

コア成果物

• task.md
• implementation_plan.md
• walkthrough.md

メタデータ

• *.metadata.json

バージョンスナップショット

• task.md.resolved.0 ... N
• implementation_plan.md.resolved.0 ... N
• walkthrough.md.resolved.0 ... N

追加のシグナル

• その他の .md 成果物
• 成果物の更新にわたるタイムスタンプ
• プラン/ウォークスルーで言及されたファイル/フォルダ/サブシステム名
• 検証/テストに関する文言
• 明示的な受け入れ基準、制約、非目標、ファイルターゲット

会話ごとに記録:

ライフサイクル

• has_task
• has_plan
• has_walkthrough
• is_completed
• is_abandoned_candidate = タスクは存在するがウォークスルーがない

リビジョン/変更量

• task_versions
• plan_versions
• walkthrough_versions
• extra_artifacts

スコープ

• task_items_initial
• task_items_final
• task_completed_pct
• scope_delta_raw
• scope_creep_pct_raw

タイミング

• created_at
• completed_at
• duration_minutes

内容/品質

• objective_text
• initial_plan_summary
• final_plan_summary
• initial_task_excerpt
• final_task_excerpt
• walkthrough_summary
• mentioned_files_or_subsystems
• validation_requirements_present
• acceptance_criteria_present
• non_goals_present
• scope_boundaries_present
• file_targets_present
• constraints_present

---

ステップ 3: プロンプトの十分性

冒頭のリクエストを 0～2 の尺度で採点します:

• 明確さ
• 境界の明確さ
• テスト可能性
• アーキテクチャの具体性
• 制約の認識
• 依存関係の認識

作成するもの:

• prompt_sufficiency_score
• prompt_sufficiency_band = High / Medium / Low

次に、どの不足していたプロンプト要素がその後の摩擦の原因になった可能性が高いかを記録します。

短いプロンプトをデフォルトで減点しないでください。狭く明白なタスクであれば、十分性が高くなることがあります。

---

ステップ 4: スコープ変更の分類

スコープ変更を次のように分類します:

• Human-added scope — 元のタスクを超えた新しい要求
• Necessary discovered scope — 元のタスクを正しく完了するために必要な作業
• Agent-introduced scope — エージェントによって導入された、おそらく不要な作業

記録するもの:

• scope_change_type_primary
• scope_change_type_secondary (任意)
• scope_change_confidence
• 根拠

キャリブレーション用に短い例を 1 つ覚えておいてください:

• Human-added: 「ここにいるついでに近くのコードもリファクタリングして」
• Necessary discovered: 元のタスクを機能させるために修正が必要な隠れた依存関係
• Agent-introduced: 要求されておらず、必要でもない追加のクリーンアップや再設計

---

ステップ 5: 手戻りの形状

各セッションを次のいずれか 1 つの主要パターンに分類します:

• Clean execution
• Early replan then stable finish
• Progressive scope expansion
• Reopen/reclose churn
• Late-stage verification churn
• Abandoned mid-flight
• Exploratory / research session

記録するもの:

• rework_shape
• rework_shape_confidence
• 根拠

---

ステップ 6: 根本原因分析

クリーンでないすべてのセッションに対して、次を割り当てます:

主要な根本原因

次のいずれか:

• SPEC_AMBIGUITY
• HUMAN_SCOPE_CHANGE
• REPO_FRAGILITY
• AGENT_ARCHITECTURAL_ERROR
• VERIFICATION_CHURN
• LEGITIMATE_TASK_COMPLEXITY

二次的な根本原因

実質的に関連する場合のみ任意

根本原因のガイダンス

• SPEC_AMBIGUITY: 冒頭の要求に境界、対象、基準、または制約が欠けていた
• HUMAN_SCOPE_CHANGE: ユーザーがタスクを広げたためにスコープが拡大した
• REPO_FRAGILITY: 隠れた結合、壊れやすいファイル、不明確なアーキテクチャ、または環境の問題が追加作業を強いた
• AGENT_ARCHITECTURAL_ERROR: 誤ったファイル、誤った前提、誤ったアプローチ、ハルシネーションによる構造
• VERIFICATION_CHURN: 実装はおおむね機能したが、テスト／検証がループを引き起こした
• LEGITIMATE_TASK_COMPLEXITY: 難易度から見て修正は想定内であり、明確に回避可能ではなかった

すべての根本原因の割り当てには次を含める必要があります:

• 根拠
• より強い代替原因が却下された理由
• 確信度

---

ステップ 6.5: セッション重大度スコアリング (0～100)

各セッションに、注意を優先するための重大度スコアを割り当てます。

構成要素 (合計、0～100 にクランプ):

• 完了失敗: 0～25 (abandoned = 25)
• 再計画の強度: 0～15
• スコープの不安定性: 0～15
• 手戻りの形状の重大度: 0～15
• プロンプト十分性の不足: 0～10 (low = 10)
• 根本原因の影響: 0～10 (REPO_FRAGILITY / AGENT_ARCHITECTURAL_ERROR が最も高い)
• ホットスポットの再発: 0～10

バンド:

• 0～19 Low
• 20～39 Moderate
• 40～59 Significant
• 60～79 High
• 80～100 Critical

記録するもの:

• session_severity_score
• severity_band
• severity_drivers = 上位 2～4 の寄与要因
• severity_confidence

重大度は優先順位付けのシグナルとして使用し、判定として扱わないでください。常にドライバーを説明してください。 セッションの意図を用いて重大度を文脈化し、調査／探索セッションが過度に減点されないようにしてください。

---

ステップ 7: サブシステム／ファイルのクラスタリング

すべての会話にわたって、ファイル、フォルダ、またはサブシステムごとに繰り返される苦戦をクラスタリングします。

各クラスタについて計算します:

• それに触れた会話の数
• 平均修正回数
• 完了率
• 放棄率
• 一般的な根本原因
• 平均重大度

目標: 摩擦が主にプロンプト由来なのか、エージェント由来なのか、それとも特定のリポジトリ領域に集中しているのかを特定すること。

---

ステップ 8: 比較コホート

比較する:

• 一発成功 vs 再計画されたセッション
• 完了 vs 中断
• プロンプト十分性が高い vs プロンプト十分性が低い
• 狭いスコープ vs スコープ拡大が大きい
• 短いセッション vs 長いセッション
• 摩擦の少ないサブシステム vs 摩擦の多いサブシステム

各比較について、次を特定します:

• 実質的に異なる点
• どのプロンプト特性がよりスムーズな実行と相関するか
• どのリポジトリ特性が繰り返しの苦戦と相関するか

単に平均を言い換えるのではなく、慎重で証拠に基づいたパターンを抽出してください。

---

ステップ 9: 気づきにくい発見

単純な指標の言い換えではない 3〜7 件の発見を生成します。

各発見には次を含める必要があります:

• 観察
• なぜ重要か
• 証拠
• 信頼度

強力な発見の例:

• 再計画は、弱い受け入れ基準よりも、弱いファイルターゲティングの周辺に集中する
• スコープ拡大は、初期成功の後に始まることが多く、成功後の人為的な拡張を示唆する
• 認証関連の苦戦は、エージェントのハルシネーションよりもリポジトリの脆弱性によって引き起こされることが多い

---

ステップ 10: レポート生成

次の構造で session_analysis_report.md を作成します:

📊 セッション分析レポート — [プロジェクト名]

生成日時: [timestamp]
分析した会話: [N]
期間: [earliest] → [latest]

エグゼクティブサマリー

指標	値	評価
一発成功率	X%	🟢/🟡/🔴
完了率	X%	🟢/🟡/🔴
平均スコープ拡大	X%	🟢/🟡/🔴
再計画率	X%	🟢/🟡/🔴
所要時間の中央値	Xm	—
平均セッション深刻度	X	🟢/🟡/🔴
高深刻度セッション	X / N	🟢/🟡/🔴

しきい値:

• 一発成功: 🟢 >70 / 🟡 40〜70 / 🔴 <40
• スコープ拡大: 🟢 <15 / 🟡 15〜40 / 🔴 >40
• 再計画率: 🟢 <20 / 🟡 20〜50 / 🔴 >50

平均深刻度の目安:

• 🟢 <25
• 🟡 25〜50
• 🔴 >50

注: 平均深刻度は集約された健全性シグナルであり、セッションごとの深刻度バンドとは異なります。

次に、何がうまくいっているか、何が破綻しているか、そして主な問題がプロンプト品質、リポジトリの脆弱性、ワークフローの規律、または検証の空回りのどれであるかについて、短いナラティブサマリーを追加します。

根本原因の内訳

根本原因	件数	%	備考

プロンプト十分性分析

• 十分性の高いプロンプトに共通する特性
• 十分性の低いプロンプトに共通する不足入力
• どの不足プロンプト要素が再計画または中断と最も相関するか

スコープ変更分析

分離する:

• 人為的に追加されたスコープ
• 発見された必要なスコープ
• エージェントが導入したスコープ

手戻り形状分析

セッション全体にわたる主な失敗パターンを要約します。

摩擦ホットスポット

再計画、中断、検証の空回り、および高い深刻度に最も関連するファイル/フォルダ/サブシステムを示します。

一発成功

最もクリーンなセッションを列挙し、それらを機能させた要因を抽出します。

気づきにくい発見

証拠に基づいた 3〜7 件の発見を信頼度とともに列挙します。

深刻度トリアージ

最も深刻度の高いセッションを列挙し、最善の介入が次のどれであるかを述べます:

• プロンプト改善
• スコープの規律
• 的を絞ったスキル/ワークフロー
• リポジトリのリファクタリング / アーキテクチャのクリーンアップ
• 検証/テストハーネスの改善

推奨事項

各推奨事項には次を使用します:

• 観察されたパターン
• 考えられる原因
• 証拠
• 行うべき変更
• 期待される効果
• 信頼度

会話ごとの内訳

#	タイトル	意図	所要時間	スコープ Δ	計画改訂	タスク改訂	根本原因	手戻り形状	深刻度	完了?

---

ステップ 11: 任意の分析後改善

適切であれば、次も行います:

• ローカルのプロジェクト健全性またはメモリ成果物 (存在する場合) を、再発する失敗モードと脆弱なサブシステムで更新する
• 十分性の高い / 一発成功セッションから prompt_improvement_tips.md を生成する
• 同じサブシステムまたはタスクシーケンスが繰り返し苦戦を引き起こす場合、不足しているスキルまたはワークフローを提案する

ワークフロー/スキルは、パターンが繰り返し現れる場合にのみ推奨してください。

---

最終出力の標準

ワークフローは以下を生成する必要があります：

1. 指標の要約
2. 根本原因の診断
3. プロンプトの十分性評価
4. サブシステム／摩擦マップ
5. 重大度のトリアージと優先順位付け
6. 証拠に基づく推奨事項
7. 直感的に気づきにくい知見

偽の精度よりも、明示的な不確実性を優先してください。

制限事項

• このスキルは、タスクが上記の範囲に明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が欠けている場合は、停止して確認を求めてください。