aep-reflect

振り返る

フィードバックのループを閉じます。現実世界での観察を、プロダクトコンテキスト（ストーリーグラフ、アーキテクチャ、さらには機会仮説）に対する実行可能な変更へと変換します。

この手順の位置づけ：

/aep-envision → /aep-map → /aep-scaffold → [ /aep-design → /aep-launch → /aep-build → /aep-wrap ] → /aep-reflect
                                                                          ▲ you are here

セッション： メイン、ユーザーとの対話型 入力： リリース後の観察（ユーザーテスト、エラーログ、コストデータ、プロダクトに対する直感） 出力： 分類済みのフィードバックと更新済みの product-context.yaml。プロダクトの意図が変わった場合は、更新済みの product/index.yaml も含みます（分割モード）。

---

開始前

モードの意味（split、v1、新規プロジェクト）は references/file-resolution.md に定義されています。そこでプローブを実行してください。Reflect は、意図していた内容を把握するために product/index.yaml（split）または product-context.yaml（v1）からプロダクト定義を読み込み、実際に起きたことを把握するために product-context.yaml から運用状態（cost、stories、changelog）を読み込みます。運用上の変更は product-context.yaml に書き込み、プロダクトの意図に関する変更は product/index.yaml（split）または product-context.yaml（v1）に書き込みます。どちらのファイルも存在しない場合は振り返る内容がありません。まず /aep-envision、次に /aep-map を実行してください。

---

ステップ 1：フィードバックを収集する

すべての情報源から観察を収集します。

• ユーザーテスト： うまくいったことは何ですか？ユーザーが戸惑ったのはどこですか？不足していたものは何ですか？
• エラーログ／モニタリング： 実行時の障害、パフォーマンスの問題、予期しない挙動
• コストデータ： product-context.yaml の cost セクションを確認します。エージェントの実行トレースがある場合は、ストーリーごとのコストを確認します。どの種類のストーリーにコストがかかりましたか？リトライはどこに集中しましたか？
• プロダクトに対する直感： 実際に動くものを見た後、ユーザーは直感的にどう感じていますか？しっくりくるのは何で、違和感があるのは何ですか？
• ドッグフーディングの報告： .dev-workflow/dogfood-*.md を読み込みます。各 ## の指摘を dogfood_report アダプター（references/telemetry-ingestion.md → Dogfood-report adapter）を使って正規化し、ステップ 2 で分類するのと同じ観察レコードにします。これは /aep-watch がヘッドレスで取り込むものと同じ情報源です。
• 学んだ教訓： lessons-learned/*.md を読み込みます（ビルド中にワークスペースエージェントが記録した観察内容です）。繰り返し発生するエラー、うまくいった解決策、不足しているドキュメントを要約します。
• レイヤーの要約： lessons-learned/distillations/*.yaml を読み込みます。これは、レイヤー完了時に /aep-wrap の Reflect と Advance が作成する、提案のみの統合結果です。各項目を distillation アダプター（references/telemetry-ingestion.md → Distillation adapter）を使って正規化します。refinements → refinement（target_layer を含む）、skill_amendments → process（提案扱いとし、自動適用はしません）、weak_areas → discovery/refinement とします。

自動取り込み（任意）： エラーログ、分析データ、モニタリング情報は、references/telemetry-ingestion.md に従って直接取り込み、同じ観察形式に正規化できます。topology.routing.telemetry_sources でエンドポイントを設定します。取り込まれたレコードは分類前に人間からの入力と統合され、各分類は引き続き人間が確認します。

事後条件： 上記のすべての情報源を確認し、その指摘をステップ 2 用の観察レコードに正規化するか、今サイクルではその情報源に該当する内容がないことを明示します。

---

ステップ 2：各観察を分類する

すべてのフィードバックを、以下の 5 つのカテゴリのいずれか 1 つに分類します。各分類をユーザーに提示し、必要に応じて変更してもらいます。どのフレームワークよりも、ユーザーのほうが自身のプロダクトをよく理解しています。このセクションが正式な分類基準です。/aep-watch もこれをヘッドレスで適用します。

バグ

仕様で定められた動作が機能しないことです。

• アクション： product-context.yaml の stories セクションに、現在のレイヤーの priority: high と status: pending を指定して新しいストーリーを直接追加し、/aep-dispatch に引き継ぎます。

改善

改善が必要な動作、またはレイヤー間で移動が必要な既存のストーリーです。

• アクション： 次のレイヤーの stories セクションに、status: pending の新しいストーリーを追加します（レイヤーの割り当てと依存関係を含めてください）。または、学習によってより早い段階で必要だとわかった場合は、既存のストーリーを後のレイヤーから前のレイヤーに昇格させます。

サブタイプ — キャリブレーション： 「正しく動作する」と「しっくりくる」の間にあるギャップです。コードは仕様どおりに動作し、仕様にも問題はありませんが、結果が人間の望んでいたものと一致しません。確認してください。コードは仕様どおりに動作していますか（はい → バグではありません）？仕様に問題はありませんでしたか（はい → 新たな発見ではありません）？結果はしっくりきますか（いいえ → キャリブレーションです）？どの側面にずれがありますか（visual-design / ux-flow / api-surface / data-model / scope-direction / copy-tone / performance-quality）？

側面の重みに応じて振り分けます。重い／軽いの区分は /aep-map の references/alignment-layers.md で規定されています。

• 重い側面：次の .5 アライメントレイヤーに calibration_type: <dimension> を指定してストーリーを作成し、振り分ける前に /aep-calibrate <dimension> を実行します。
• 軽い側面：直接 /aep-calibrate <dimension> に振り分けます。次の整数レイヤーにストーリーを作成するか、プロダクトコンテキストをインラインで更新する場合があります。.5 レイヤーは不要です。

発見

新しい要件、または無効になった前提です。

• アクション： プロダクトコンテキストを見直します。プロダクトの前提に関するもの → /aep-envision を使って product セクションを更新します（影響を受ける前提に改訂済みの印を付けてください）。アーキテクチャ上の問題 → /aep-map を使って architecture セクションを更新します。

機会の変化

当初の機会仮説が誤っていた、または変化したことで、投資判断が根本的に変わります。

• アクション： /aep-envision のフェーズ 0 に戻ります。兆候：解決しようとしている問題が、ユーザーが実際に抱えている問題ではない、または市場の変化により機会が意味を失った。

プロセス

プロダクトではなく、ワークフロー自体に関する観察事項です（権限による停滞、シグナルの陳腐化、ツールの不足、エージェント設定の不足）。

• アクション： パターンを lessons-learned/process/<observation>.md に記録します（発生した事象 — 説明、頻度、影響。判明している場合は根本原因。提案する軽減策）。process_learnings エントリー（pattern、mitigation、discovered_at）を product-context.yaml の topology.routing に追加します。
• スキルの修正： パターンにスキルファイルの変更が必要な場合は、changelog に修正案として記録します。type: process-improvement、summary、および proposed_changes（skill、change、rationale）を含めます。スキルファイルは人間がレビューして適用します。分類器は修正案を提示するだけで、スキルファイルを編集することはありません。
• 上流への振り分け： 複数の下流実行にわたるプロセスと技術スタックの観察事項を体系的に取り込むには、/aep-workflow-feedback を使用します（標準化された形式と、下流から AEP への振り分け）。

事後条件： すべての観察事項には、ユーザーが確認したカテゴリが正確に 1 つ割り当てられ、その振り分けアクションが記録されています。つまり、ストーリーが stories に追加される、product／architecture の更新がキューに登録される、または process_learnings／修正案のエントリーが書き込まれます。

---

ステップ 2.5：マップを再スライスする

すべてのフィードバックを分類したら、現在のレイヤー割り当てを見直します。リリースラインは鉛筆で引いた印であり、学んだことに応じて動かします。

まだ構築していない各レイヤーについて、分類済みフィードバックに照らしてストーリーの優先順位を見直します。学びによって、より早く必要だと分かったストーリーは後のレイヤーから繰り上げ、重要度が低いと分かったものは繰り下げます。分類済みの改善項目から新しいストーリーを適切なレイヤーに追加し、product-context.yaml の stories セクションにある layer の割り当てを更新します。

重要なルール： 再スライスのために /aep-envision に戻る必要はありません。そこへ進むのは、背骨（ユーザーの活動）やプロダクトの位置付けが変わる場合のみで、レイヤーの割り当てが変わる場合ではありません。フレームワークの全容については、docs/decisions/release-line-adjustments.md を参照してください。

事後条件： stories の layer の割り当てに分類済みフィードバックが反映されているか、変更がなかったため割り当てが変更されていません。

---

ステップ 2.75：成果契約を評価する

完了したレイヤーに product.layers[] で outcome_contract が定義されている場合：

1. 仮説を提示する：「仮説は次のとおりでした：[hypothesis]。成功指標は [type] [target] でした。」
2. 評価を依頼する — 成果契約は自動テストではありません。ユーザーテスト、分析データの確認、または定性的な評価が必要になる場合があります。
3. 判定ルールを適用する： keep_if の条件を満たした場合 → 合格として記録し、次のレイヤーに進みます。otherwise が該当する場合 → 不合格として記録し、再スライスを推奨します（後のレイヤーからストーリーを繰り上げ、必要に応じて背骨を調整します）。
4. 結果を changelog に記録する — type: outcome_evaluation とし、指標、実測値、目標値を含め、合格または不合格だったことを summary に記載します。

自動評価（任意、オプトイン）： 指標がテレメトリに紐付いている場合、一時停止を省略できます。topology.routing.auto_outcome_eval のモードについては、references/telemetry-ingestion.md を参照してください。quantitative は coverage_check ゲート（§1.5）を実行し、指標がソースに紐付いている場合は実測値を取得して、keep_if／otherwise を機械的に適用します。指標が紐付いていない場合や取得に失敗した場合は、人による確認に切り替わります。定性的な指標では一時停止します。ただし、topology.routing.full_auto: true の場合は、エージェントが独自の判断で評価します。デフォルト（auto_outcome_eval: none、full_auto: false）では、人間が介在する一時停止がそのまま維持されます。

完了したレイヤーに成果契約が存在しない場合は、このステップをスキップします。

事後条件： 成果の結果が合格または不合格として changelog に記録されているか、product.layers[] に outcome_contract がなかったためこのステップがスキップされています。

---

ステップ 3：コストレビュー

product-context.yaml の cost セクションと、.dev-workflow/ にある実行トレースを確認します。

• 一貫してコストが高いストーリーの種類はどれですか？ コンテキストの組み立てをより正確にする、分解を簡素化する、または別のエージェントの役割を使うことで改善できるでしょうか？
• リトライが集中したのはどこですか？ 失敗のパターンから、仕様が曖昧だったか、モジュール境界が不適切だった可能性が分かります。
• エージェントのトポロジーは効率的ですか？ ルーティングポリシーを調整する必要がありますか？

事後条件： コストに関する所見とトポロジー調整の推奨事項は、ステップ 4 に向けて記録されています（リフレクションの changelog エントリーに cost_observations として記録、および／または topology を編集）。または、今サイクルでは該当なしと明記されています。

---

ステップ 4：プロダクトコンテキストを更新する

分類したフィードバックに基づき、該当するファイルを更新します。運用上の変更（新しいストーリー、アーキテクチャの修正、トポロジー、コスト、変更履歴）は product-context.yaml に、プロダクトの意図に関する変更（機会の変化、ペルソナの変更、目標、mvp_boundary、レイヤー、アクティビティ）は product/index.yaml（分割モード）または product-context.yaml（v1 モード）に反映します。

1. プロダクトコンテキストのスキーマに従って changelog エントリーを追記します — date、type: reflection、summary、および bugs（description、story_id）、refinements（description、story_id、target_layer）、discoveries（description、affected_section）、opportunity_shifts（description）を含む feedback マップに加え、cost_observations を記載します。

2. stories セクションを更新します。新しいストーリーを追加します（バグ修正には priority: high を設定し、改善は次のレイヤーに追加します）。

3. 前提が変わった場合は、product セクションを更新します（変更にバージョンを付けます）。

4. ルーティングの調整が必要な場合は、topology セクションを更新します。

5. YAML を検証します（チェックリスト全体と一般的な修正については references/yaml-guardrails.md を参照してください）。

   npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"
   

コミットする前に、エラーをすべて修正します。

6. 「Control-Plane Commits」の /aep-git-ref に従ってコミットします（「Resolving $BASE」の /aep-git-ref に従って $BASE を解決します）。

   git pull --ff-only origin "$BASE"
   git add product-context.yaml product/
   git commit -m "chore: reflect — classify feedback and update product context"
   git push origin "$BASE"
   

事後条件： npx js-yaml が YAML OK を出力し、git push が終了コード 0 で終了していること。

---

ステップ 5：次のアクションを決める

振り返りに基づいて、次のステップを提案します。

フィードバックの種類	次のアクション
バグのみ	YAML に追加されたストーリーを修正 → /aep-dispatch → /aep-design → /aep-build
改善	YAML に次のレイヤーのストーリーを追加 → /aep-dispatch → /aep-design → /aep-build
発見（プロダクト）	前提を更新するために /aep-envision
発見（アーキテクチャ）	システムマップを更新するために /aep-map
機会の変化	/aep-envision Phase 0（再検証）
キャリブレーション（大規模）	.5 のアラインメントストーリーを作成 → /aep-calibrate <dimension> → /aep-dispatch
キャリブレーション（小規模）	/aep-calibrate <dimension>（インライン）→ ストーリーを更新する場合があります → /aep-dispatch
問題なし	次のレイヤーに進むか、本番環境にリリース

事後条件： 表にある次のアクションがユーザーに提案されていること。