omh-deep-interview

OMH Deep Interview — 対話を通じた要件仕様の策定

使用する場面

• 目標が曖昧、詳細が不足している、または複数の解釈が可能な場合
• 計画（omh-ralplan）や、複雑な作業の実装に着手する前
• ユーザーが「詳細なインタビュー」「要件」「何を作るべきか」「一緒に考えてほしい」と言った場合
• omh-ralplanで、目標が曖昧すぎて計画できないと判断された場合
• ユーザーが実際に何を望んでいるのか確信が持てない場合
• ドメインへの不慣れ： 目標の達成に、なじみのないドメインに関する外部知識が必要な場合は、まず omh-deep-research を実行して背景情報を集め、その後、確認済みのレポートを入力としてインタビューを再開するよう提案します。

使用しない場面

• 目標がすでに明確で、範囲も限定されている場合
• このプロジェクトの .omh/specs/ に確認済みの仕様書がすでに存在する場合
• ユーザーが要件の聞き取りを明示的に省略したい場合
• タスクが明白な、些細な単一ファイルの変更の場合

前提条件

• ユーザーと対話できること（このスキルでは質問を行い、回答が必要です）
• 状態ファイルと仕様書を保存するための .omh/ ディレクトリへの書き込み権限

手順

以下のフェーズを順番に実行します。このスキルでは、ユーザーとの対話と、 状態ファイルおよび仕様書の出力に向けたファイルの書き込みを行います。

Phase 0: 既存の状態を確認する

新しいインタビューを開始する前に、次の手順を実行します。

1. アクティブなインタビューをすべて列挙します。

   listed = omh_state(action="list_instances", mode="interview")
   

   各エントリには instance_id（インタビュー ID）と active フラグが含まれます。 omh_state が利用できない場合は、.omh/state/interview--*.json を手動で glob します。
2. アクティブなインタビューが存在する場合は、ユーザーに次のように伝えます。「『{project_name}』のアクティブなインタビューがあります（id={id}）。再開、新規開始、または中止のどれにしますか？」
3. 再開する場合：omh_state(action="read", mode="interview", instance_id="{id}") を実行し、ラウンドの要約を読んでコンテキストを再構成します。
4. 中止する場合：omh_state(action="write", mode="interview", instance_id="{id}", data={...status: "abandoned"}) を実行してから、新しい ID で Phase 1 に進みます。
5. アクティブな状態が見つからない場合：Phase 1 に進みます。
6. 異なるプロジェクトでの並行インタビューは許可されています。妨げないでください。
7. 既存のリサーチコンテキスト（omh-deep-research のセンチネル）を確認します： .omh/research/*-report.md のいずれかにフロントマターがあり、 status: confirmed となっている場合は、そのレポートをインタビューに利用できるコンテキストとしてユーザーに伝えます （例：「『{topic}』に関する確認済みリサーチレポートが {path} にあります。背景情報として取り込みますか？」）。自動で読み込まず、ユーザーに判断してもらいます。

Phase 1: 開始

次の2つの質問からインタビューを始めます。

1. プロジェクトの説明：「作りたいものを2～3文で説明してください。中心となるアイデアは何ですか？」
2. 新規プロジェクトか既存プロジェクトか：「ゼロから始める新しいプロジェクトですか？それとも既存のコードベースやシステム内で作業していますか？」

次に、以下を行います。

• インタビュー ID を生成します：di-{YYYYMMDD}-{short_random}（例：di-20260407-x7k）
• ファイル名に使用する短いプロジェクト名をユーザーに尋ねます。
• .omh/state/interview--{id}.json に状態ファイルを作成します（エンジンが instance_id="{id}" からこのファイル名を導出します）。内容は次のとおりです。
  • すべての網羅性の次元を HIGH に設定
  • ユーザーの回答に基づき、type を greenfield または brownfield に設定
  • 新規プロジェクトの場合、existing_context の網羅性を N/A に設定
  • 開始時の回答を記録したラウンド 0 の要約
• ユーザーに次のように伝えます。「了解しました。要件を明確にするため、最大5ラウンドの質問をします。必要な内容を確認できたと感じたら、いつでも『十分です』と言ってください。」

フェーズ 2：インタビューループ

最大 5 ラウンド実施します（ユーザーが希望する場合は最大 10 ラウンドまで延長できます）。各ラウンドでは、次の手順を行います。

ステップ 1 — 探るディメンションを選択する

ディメンションごとのカバレッジ区分を比較します。曖昧さが最も大きいディメンションを対象にします。 複数のディメンションが同じ区分の場合は、重みを使って優先順位を決めます。

• グリーンフィールド：Goal（0.40） > Constraints（0.30） = Success Criteria（0.30）
• ブラウンフィールド：Goal（0.35） > Constraints（0.25） = Success Criteria（0.25） > Existing Context（0.15）

各区分の詳細な定義と例については、references/scoring-rubric.md を読み込みます。

ステップ 2 — 質問する

選択したディメンションを対象に、主要な質問を 1 つします。ユーザーがこれまでに伝えた内容に基づいた、具体的な質問にしてください。一般的な質問は避け、以前の回答に言及します。

良い例：「個人利用の CLI ツールだとおっしゃっていました。タスクが設定されていない状態で実行すると、デフォルトのリストを作成する、エラーを表示する、それとも別の動作をするのでしょうか？」

悪い例：「制約は何ですか？」

回答が不明瞭、矛盾している、または新たな疑問が生じる場合は、簡潔な追加質問を 1～2 回行ってかまいません。回答が明確なら、追加質問を無理に行わないでください。

ステップ 3 — 適応型の質問（行き詰まった場合）

あるディメンションを 2 ラウンド以上連続して対象にしても、現在の区分から進展しない場合は、質問の仕方を変えます。

• まったく異なる角度から質問する
• 具体例を提示し、「これは正しいですか？ それとも、どこを変更しますか？」と尋ねる
• 明確にするうえで何が妨げになっているか尋ねる：「何が特定を難しくしていますか？」
• 曖昧に使われている特定の用語について、ユーザーに定義してもらう

ステップ 4 — カバレッジを更新する

ユーザーの回答を処理した後、対象のディメンションのカバレッジ区分を再評価します。 references/scoring-rubric.md のルーブリックを使用します。慎重に判断し、迷う場合は、時期尚早に区分を下げるのではなく、現在のレベルを維持します。

ステップ 5 — 状態を更新する

インタビューの状態を更新します（ラウンド数を加算し、要約を追加し、カバレッジを更新します）。

omh_state(action="write", mode="interview", instance_id="{id}", data={...updated state with new round...})

各ラウンドの要約は最大約 200 語とし、やり取り全体ではなく、そこで得られた内容を記録します。

ステップ 6 — カバレッジを示し、続行するか尋ねる

現在の状況をユーザーに示します。

Coverage after round {N}:
  Goal:             [MEDIUM]  →  Some clarity, but scope needs bounding
  Constraints:      [LOW]     →  Mostly clear, data format TBD
  Success Criteria: [HIGH]    →  Need testable criteria
  Existing Context: [N/A]     →  Greenfield project

次に、**「引き続き内容を詰めますか？ それとも、この内容で進められそうですか？」**と尋ねます。

• ユーザーが続行すると答えた場合：次のラウンドに進む
• ユーザーが十分、完了、これで終わりと答えた場合：フェーズ 3 に進む
• 5 ラウンドに達した場合：「5 ラウンド実施しました。続けますか（さらに最大 10 ラウンドまで）、それとも、現時点の内容から仕様を生成しますか？」
• 10 ラウンドに達した場合：自動的にフェーズ 3 に進む

終了するタイミングは常にユーザーが決めます。カバレッジスコアを基準に自動終了してはいけません。

フェーズ 3：仕様の生成

ユーザーが終了を確定したとき（または最大ラウンド数に達したとき）：

1. templates/spec-template.md を読み込みます
2. 状態ファイルに蓄積された各ラウンドの要約から仕様をまとめます
3. テンプレートのすべてのセクションに記入します。
   • Goal：Goal ディメンションを対象にしたラウンドからまとめます
   • Constraints：制約に焦点を当てたラウンドからまとめます
   • Success Criteria：具体的でテスト可能な内容にします。検証できない基準は、「Open Questions」に記載します
   • Existing Context：ブラウンフィールドの場合のみ記入し、コンテキストに焦点を当てたラウンドからまとめます
   • Assumptions：ユーザーが明言または示唆したものの、まだ検証されていない事項
   • Open Questions：カバレッジが HIGH または MEDIUM のままの項目。これらは未解決です
4. YAML フロントマターを設定します。
   • status: draft
   • coverage：現在の区分値
   • rounds_completed：完了したラウンドの合計数
5. .omh/specs/{project-name}-spec.md に書き込みます
6. 状態を更新します：spec_file = 仕様ファイルへのパス

フェーズ 4：確認

仕様書の全文をユーザーに提示し、次のように尋ねます。

「こちらが作成した仕様書です。内容をご確認ください。次のいずれかを選べます。

• 確認する — 仕様書を確定します。後続のスキル（ralplan、autopilot）で使用されます
• 変更を依頼する — 変更したい内容をお伝えください。追加で質問します
• 破棄する — 仕様書を破棄して、ヒアリングを終了します」

各応答には次のように対応します。

確認する場合：

• 仕様書のフロントマターを更新します：status: confirmed
• 状態を更新します：status: confirmed
• ユーザーに次のように伝えます：「仕様書を確認し、{path} に保存しました。これで omh-ralplan を使って、この仕様書から実装計画を作成できます。」

変更を依頼された場合：

• ユーザーが変更したい具体的なセクションについて、的を絞った追加質問をします
• 仕様書を再生成します
• 確認のプロンプトに戻ります

破棄する場合：

• 仕様書ファイルを削除します
• 状態を更新します：status: abandoned
• ユーザーにヒアリングを破棄したことを伝えます

下流のスキルで有効と見なされるのは、status: confirmed の仕様書のみです。

フェーズ 5：ログ記録

ヒアリング中は、構造化されたイベントを .omh/logs/interview-{id}.log に記録します。

2026-04-07T06:30:00Z STARTED interview_id=di-20260407-x7k project=my-project type=greenfield
2026-04-07T06:31:15Z ROUND round=1 dimension=goal coverage_change=goal:HIGH→MEDIUM
2026-04-07T06:33:42Z ROUND round=2 dimension=constraints coverage_change=constraints:HIGH→LOW
2026-04-07T06:35:00Z USER_EXIT round=3 reason=user_confirmed
2026-04-07T06:35:30Z SPEC_GENERATED path=.omh/specs/my-project-spec.md status=draft
2026-04-07T06:36:00Z SPEC_CONFIRMED path=.omh/specs/my-project-spec.md

記録するのはイベントと決定事項のみです。会話内容は記録しません。

センチネル規約

下流のスキルは、YAML フロントマターに status: confirmed が設定されている .omh/specs/*-spec.md に一致するファイルを確認し、完了したヒアリングを検出します。

• omh-ralplan：確認済みの仕様書が存在する場合、ユーザーに目標の説明を求める代わりに、プランナーのサブエージェントへの目標／仕様入力として使用します。
• omh-autopilot：確認済みの仕様書が存在する場合、フェーズ 0（要件）を完全にスキップします。

状態管理

状態ファイル：.omh/state/interview--{id}.json（エンジンのパス。omh_state に instance_id="{id}" を渡します）

完全なスキーマについては、references/state-schema.md を参照してください。

主なルール：

• 各ヒアリングは ID で識別される個別のインスタンスです。異なるプロジェクトであれば、並行してヒアリングできます
• 状態にはラウンドの要約（各約 200 語まで）が保存され、会話の全文は保存されません
• 状態は完了後も保持されます（監査証跡のため）
• 再開時に復元できる情報には本質的に欠落があります。ラウンドの要約は文脈の再構成に役立ちますが、元の会話の細かなニュアンスは失われます

注意点

• スコアに基づいて自動終了しないでください。 カバレッジ区分は、質問対象を決めるための参考ヒューリスティックです。終了のタイミングは常にユーザーが決めます。
• 会話の全文を保存しないでください。 ラウンドの要約を使えば状態を簡潔に保て、再開時のコンテキストウィンドウの制限も尊重できます。再開による復元は正確ではなく、おおよそのものだと認識してください。
• 既存コードへの変更かどうかは尋ね、自動判定しないでください。 package.json などの有無を確認する方法は信頼性に欠け、決めつけにもなります。ユーザーに説明してもらいましょう。
• プロジェクトごとに有効なヒアリングは 1 つまでです。 ヒアリングごとに新しい instance_id を使用します。同じプロジェクトで有効なヒアリングがすでに存在する場合は、同じ ID で並行してヒアリングを開始する前に、再開するか破棄するかを提示してください。
• 仕様書は確認済みである必要があります。 下流のスキルへの入力として、草稿の仕様書は無効です。ユーザーから明示的な確認を得る必要があります。
• 一般的な質問は避けてください。 ユーザーの以前の回答を踏まえて質問します。「制約は何ですか？」では不十分です。「Linux で個人利用するとのことですが、対応が必要なほかのプラットフォームはありますか？」のように尋ねると役立ちます。
• カバレッジの評価は慎重に行ってください。 判断に迷う場合は、区分を現在のレベルに維持してください。ある側面を「明確」と早まって判断するより、もう 1 つ質問するほうが適切です。