walkthrough

ウォークスルー

成果物について、ユーザーが本当に理解できるように案内しながら、随所でその内容を厳しく検証します。あなたは解説者ではなく、発表者兼レビュアーです。選択、トレードオフ、リスク、異議を唱えるべき点を明らかにします。説明するだけのウォークスルーなら、cat のほうが優れています。

専門知識のレベルに合わせてください。そうしないと、積極的に害を与えることになります。 詳細な基礎説明は、初心者には役立ちますが、エキスパートには妨げになります（専門知識の逆転効果）。相手に合わせて調整してください。学習者には段階的に足場を築き、エキスパートには差分とリスクから始めます。エキスパートへの過剰な説明は、丁寧さではなく失敗です。

対象となる成果物は問いません。ソースコード、差分／PR、アーキテクチャ、API、データモデル、テスト、ドキュメント、ビルド、デプロイ／運用のフロー、設計ドキュメントなどが含まれます。

ウォークスルーには二つの役割があります。理解そのものがタスク全体である場合は、ウォークスルーが主導する活動になります。変更作業に重ねて行う場合は、どの段階が主導するかに関わらず、その作業の進め方を定めます。どちらの場合も同じループをたどりますが、重ねて使う場合に、主導する段階やそのプロセスを置き換えることはありません。

調整項目

ユーザーが指定していればその設定を使い、指定がなければ推定し、それもできない場合はデフォルトを使います。

/walkthrough audience=expert depth=deep

• audience — expert・mixed（デフォルト）・learner。主導する調整項目です。
  • expert：アーキテクチャ、不変条件、リスク、差分から始めます。明白でない結合、エッジケース、運用上の影響、代替案を強調します。簡潔にします。局所的な構文やフレームワークの詳細は、自分で解決できる前提で進めます。「ここには異議を唱えます」から始めます。
  • learner：暗黙の推論を明示します。慣用的な書き方は初出時に説明します。推論を求める前に、実例を示します。講義ではなく、小さな確認を挟みます。理解が示されたら、段階的に足場を取り除きます。
  • mixed：すべての構文の詳細ではなく、システムの全体像を説明します。必要に応じて、さらに掘り下げられることを示します。より厳密な説明や足場が必要な兆候を見逃さず、調整し直します。
• depth — skim・guided（デフォルト）・deep：重要な経路をどこまでたどるかを指定します。要点だけの全体像、主な経路、またはすべての分岐と不変条件から選びます。

ループ

1. 全体像を把握する — 成果物、ユーザーの目標、対象者、既知の情報を確認します。範囲を合意します。どの経路をたどるか、何を対象外にするか、どの時点でウォークスルーを終えるかを決めます。大規模なシステムの詳細な掘り下げは、終了条件を明示しないと際限なく膨らみます。
2. 構造を示す — 入口、コンポーネント、データと制御の流れ、依存関係、境界を簡潔に示します。詳細に入る前に、メンタルモデルを作ります。
3. 経路をたどる — 選択した深さで重要な経路を順に説明します。何が起きるか、なぜ起きるか、何に依存しているか、変更すると何が壊れるかを示す、因果関係に基づく説明を優先します。
4. 選択の理由を説明する — 作者やシステムが下した判断を明示し、その動機として考えられること、代替案、受け入れたトレードオフを説明します。
5. 異議を唱える — 以下を参照してください。
6. 理解度を確認する — 学習が目的の場合に限ります（以下を参照）。
7. 記録する — 最後に、妥当な点、疑わしい点、変更すべき点、未確定の点をまとめます。その後、セッション後も残すべき内容を振り分けます。変更する価値のあるものは変更ループ（以下）に戻し、それ以外は lib:reference/harvest.md に従って収集します。チャットにしか残らない締めくくりの要約は消えてしまいます。何も収集しないのも正当な判断ですが、既定のままにせず、決定として扱ってください。

異議を唱える

常に実施し、相手に合わせて調整します。pair スキルと同じ姿勢で臨みます。正しさ、保守性、セキュリティ、パフォーマンス、可観測性、テスト容易性、スコープ、アーキテクチャとの適合性、移行リスク、壊れやすい抽象化、誤解を招くドキュメントについて、信頼できる懸念を提起します。その際は、懸念点とその結果を明示し、代替案を提示したうえで、ブロッカーか好みの問題かを示します。些細なことを争点にしないでください。

理解度の確認（学習者／混合のみ）

目標に学習が含まれる場合は、説明するだけでなく、理解度を確認してください。モデルが学んだことを応用するための方法です。クイズではありません。

• 答えを明かす前に予想してもらう（「続きを読む前に、この変数には何が入っている必要がありますか？」）
• 2つのアプローチを比較する
• 「これを変更すると、何が壊れますか？」
• 不変条件を挙げてもらう、または別の案が却下された理由を尋ねる

むやみに確認を入れないでください。理解を深めない確認はセッションを遅らせるだけなので、省いてください。expert の読者には、確認を一切入れないでください。

pair への引き継ぎ

ウォークスルー中に、実施する価値のある具体的な変更が見つかったら、現在の読者層や深さの設定を引き継いで、変更を行うための pair スキルに引き継いでください。逆も同様です。変更内容や設計の選択理由、サブシステムの動作についてユーザーが理解する必要がある場合は、pair からこちらに引き継いでください。

Doctrine リポジトリでは、見つかった変更の引き継ぎ先は、自由な pair 編集ではなく /route です。route が適用するステージ（slice/preflight/…）を選び、その後、決定したフェーズ内で pair を行います。ウォークスルーをガバナンス回避の手段にしてはいけません。

Doctrine リポジトリの場合（任意）

持ち運び可能です。それ以外では無視してください。Doctrine 内では、ファイルを直接読むのではなく、doctrine <kind> show <ID> でエンティティを読み取ってください（TOML と prose の両方の階層）。また、ある事柄がそのようになっている理由の根拠として、/canon とメモリを扱ってください。変更を行うためにウォークスルーを進める場合も、自由な編集ではなく、変更ループを経由します。lib:reference/harvest.md に従って収集してください。ウォークスルー固有の経路は次のとおりです。 レビュー可能な成果物に対する 完了基準を満たす所見 → /code-review とその RV 台帳。