aep-calibrate

キャリブレーション

人間とのアラインメントのチェックポイントです。エージェントは仕様に沿って構築しますが、仕様は人間の意図を損失を伴う形で圧縮したものです。このスキルでは実行を一時停止し、人間が構築されたものを確認できるようにするとともに、「正しい」とは実際に何を意味するのかを、エージェントが利用できる形式で記録します。

このスキルの位置づけ：

/aep-reflect (identified alignment gap)
  → /aep-calibrate           (Phase 1: generate dimension-specific brief)
  → human explores       (method varies by type — external tools, conversation, code review)
  → /aep-calibrate capture   (Phase 2: capture decisions into artifact)
  → /aep-dispatch            (stories dispatched with calibration context)

セッション： メイン。ユーザーとの対話形式です
入力： キャリブレーションの種類 ＋ product/index.yaml（分割モード）または product-context.yaml（v1 モード）のプロダクト定義 ＋ product-context.yaml の運用状態
出力： キャリブレーション成果物（独立ファイルまたはインライン）＋ 更新された calibration.history

---

種類の判定

スキルの呼び出し方法を確認し、キャリブレーションの対象を判断します。

パス A — 明示的な指定： ユーザーが /aep-calibrate visual-design または /aep-calibrate api-surface と指定します。種類が直接指定されています。

パス B — /aep-reflect からのルーティング： リフレクションで、特定の対象を伴うキャリブレーションの必要性として観察事項が分類されます。対象と観察テキストがコンテキストとして渡されます。

パス C — 指定なし： ユーザーが種類を指定せずに /aep-calibrate と入力した場合、種類を判断します。

1. product-context.yaml（運用ファイル。両モード）にある calibration.plan を確認します。現在のレイヤーで次の対象はどれですか？
2. 現在の .5 レイヤーで calibration_type が設定されているストーリーを確認します。
3. どちらにも該当しない場合は、ユーザーに尋ねます。「何に違和感がありますか？（ビジュアルデザイン／UX フロー／API サーフェス／データモデル／スコープの方向性／文体／パフォーマンス品質）」

事後条件： 7 つの対象のうち、1 つが選択されています。

---

ファイルの解決

ls product/index.yaml 2>/dev/null && echo "SPLIT MODE" || echo "V1 MODE"
cat product-context.yaml

モードの意味は references/file-resolution.md を正とします。分割モードでは product/index.yaml からプロダクト定義（quality_dimensions、layers、activities、constraints、success_criteria、failure_model）を読み込み、v1 モードでは product-context.yaml から読み込みます。運用状態（calibration.plan、calibration.history、stories、architecture）は、常に product-context.yaml から読み込みます。各種類の書き込み先は references/calibration-types.md（書き込み先）に記載されています。

---

モードの検出

種類が決まったら、既存のキャリブレーションを確認します。

• 確立モード： calibration.history にこの対象の過去の記録がありません → 詳細なブリーフを作成し、成果物を一から作成します。
• 拡張モード： 過去の記録があります → 既存のキャリブレーションに含まれていない新しいパターンや判断だけを扱う差分ブリーフを作成します。

---

キャリブレーションの種類

各対象は 重 または 軽 のいずれかです（分類は /aep-map の references/alignment-layers.md を正とします）。これにより、フェーズ 1 からの引き継ぎ方法が決まります。

• 重： エージェントのワークフロー外のツールを使った外部調査、独立した calibration/<type>.yaml 成果物、そして通常は .5 アラインメントレイヤーのストーリーを伴います。フェーズ 1 はここで停止し、引き継ぎます。
• 軽： 対話形式の質疑応答を通じて、プロダクトコンテキストをその場で更新します。フェーズ 1 からフェーズ 2 へそのまま進みます。

対象ごとのブリーフテンプレート、調査方法、スキャン対象、書き込み先は references/calibration-types.md に記載されています。対象を選ぶときや現在の状態をスキャンするときに読み込んでください。ux-flow／visual-design については、先に /aep-design-lens を実行すると、理論に基づき深刻度をスコア化したヘルスチェック（エビデンス）がブリーフに追加され、calibrate はそれを人間の判断に変換します。

---

フェーズ 1：ブリーフの作成

ステップ 1：プロダクトコンテキストの読み込み

cat product-context.yaml

以下を抽出します。

• opportunity.bet ＋ product.problem → プロダクトのアイデンティティ
• product.persona.description ＋ product.persona.jtbd → ターゲットユーザー
• opportunity.why_now → 緊急性／ポジショニング
• layer がアクティブなレイヤーに一致する stories → 構築済み、または今後構築するもののスコープ
• product.constraints.required_stack ＋ preferred_stack → 技術的制約
• calibration.history → この対象に関する過去のキャリブレーション判断（拡張モード）

ステップ 2：現在の状態をスキャンする

このタイプのスキャン対象（references/calibration-types.md → Scan Targets の表）に照らして、現在の実装を確認します。たとえば、visual-design では globals.css／components/／routes/、api-surface では architecture.interfaces とハンドラーファイルを確認します。

ステップ 3：ブリーフを作成する

references/briefs/<type>.md にあるタイプ別のテンプレートを使用します。

• 確立モード： すべてのセクションを含むブリーフテンプレート全体を作成します。
• 拡張モード： 既存のキャリブレーション成果物またはプロダクトコンテキストのセクションを読み、現在のレイヤーで新たに対象となる内容のみを取り上げたブリーフを作成します。「現在のキャリブレーション済みシステムは次のとおりです。これらの新しい[ページ／エンドポイント／エンティティなど]には、まだ取り上げられていない判断が必要です：[一覧]」

ブリーフを docs/calibration-brief.md に書き込み、内容全体をターミナルに出力します。

事後条件： docs/calibration-brief.md が存在し、その内容が出力されています。

ステップ 4：引き継ぐ

負荷の高いキャリブレーション（visual-design、ux-flow、copy-tone）： 探索の手順を出力して、停止します。人間がエージェントの手を離れて、外部で探索します。

Calibration brief written to: docs/calibration-brief.md

Next steps (you do these):

  1. [Type-specific exploration instructions]
  2. Explore variations, then pick a direction.
  3. Save reference files to docs/design-references/ (if applicable)
  4. When ready, come back and run:
     /aep-calibrate capture

visual-design の場合は、ツールの案内として references/vibe-design-tools.md を参照するよう人間に案内します。

負荷の低いキャリブレーション（api-surface、data-model、scope-direction、performance-quality）： ブリーフを提示し、そのままフェーズ 2 に進みます。ブリーフを会話の枠組みとして使用し、外部での探索は必要ありません。

---

フェーズ 2：判断を記録する（/aep-calibrate capture）

ステップ 1：対話形式の Q&A

references/capture/<type>.md にある構造化された質問を、一度に 1 つずつ尋ねます。（負荷の高い例：選択した方向性、配色、ユーザージャーニーの判断、語調。負荷の低い例：命名の判断、エンティティ／フィールド名、スコープのギャップ評価、レイテンシのしきい値。）

事後条件： references/capture/<type>.md のすべての質問に回答しています。

ステップ 2：成果物を作成する

負荷の高いキャリブレーション：

• 確立モード： references/schemas/<type>-schema.yaml のスキーマを使用して、Q&A の回答からすべてのセクションを埋め、calibration/<type>.yaml を新規作成します。
• 拡張モード： 既存の calibration/<type>.yaml を読み込み、新たに対象となったパターンの項目を追加し、calibrated_at／calibrated_from_layer を更新します。既存の値を置き換えず、拡張してください。

visual-design では、これに加えて、記録した配色を使って globals.css も更新します。値を oklch に変換し、:root と .dark の下に CSS カスタムプロパティとして記述します。確立モードでは配色全体を置き換え、拡張モードでは新しいカスタムプロパティのみを追加します。

負荷の低いキャリブレーション： このタイプのファイル解決先にある該当セクション（references/calibration-types.md → Write Targets を参照）を更新します。対象は architecture.interfaces、architecture.domain_model、product.goals／mvp_boundary／layers、または product.success_criteria／failure_model です。

事後条件： 選択した判断が既存のスキーマフィールドに記録されています。負荷の高いキャリブレーションでは、選択した方向性が direction.name／direction.description に記載され、calibrated_at が設定された calibration/<type>.yaml が存在します。負荷の低いキャリブレーションでは、対象セクションに判断が反映されています。

ステップ 3：キャリブレーション履歴を更新する

プロダクトコンテキストのスキーマに従い、product-context.yaml の calibration.history と changelog にそれぞれ 1 件追加します。

• calibration.history の項目 — dimension、calibrated_at、calibrated_from_layer、mode（establishment|extension）、artifact_path（負荷の低いキャリブレーションでは null）、sections_updated、summary。
• changelog の項目 — date、type: calibration、author: human、summary、sections_changed。

ステップ 4：コミットする

コミット前に YAML を検証します（よくある修正方法については references/yaml-guardrails.md を参照してください）。

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

コミット前にエラーを修正します。その後、$BASE にコミットしてプッシュします（/aep-git-ref の「Resolving $BASE」に従って $BASE を解決してください）。

git pull --ff-only origin "$BASE"
git add calibration/ product-context.yaml product/
git commit -m "feat: calibrate <dimension> — <brief summary>"
git push origin "$BASE"

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