# [H] 意思決定記録フロー

ユーザーとの議論・検討・レビューの結果として意思決定が確定したとき、
その判断根拠を ADR に記録する。

## トリガー

以下のいずれかに該当する場合にこのフローを適用する：

- ユーザーとの議論で設計方針が決まった（「この方向で行こう」「こうしよう」等）
- 複数の代替案を比較検討し、1つを採用した
- 既存の設計判断を覆す変更を行った
- 「なぜこうしたのか」を将来のために残すべきと判断した
- ユーザーが明示的に ADR の作成を依頼した

## ADR を書かなくてよいケース

- 自明な実装判断（標準ライブラリの使用、命名規約の適用等）
- 一時的な回避策（IMPL の TODO に記録する）
- コードを読めば理由が明らかな変更

## 手順

### 1. 議論の要約

会話の中から以下の要素を抽出する：

| 要素 | 説明 | 例 |
|---|---|---|
| **課題** | 何が問題だったか | 「`__init__` で IO 副作用がある」 |
| **検討した選択肢** | 議論に上がった代替案 | 「ファクトリ移動 / Lazy初期化 / RAII」 |
| **決定事項** | 最終的に採用した方針 | 「DB コンストラクタで init_schema() を呼ぶ」 |
| **根拠** | なぜその判断に至ったか | 「既に __init__ が重いため一貫性がある」 |
| **トレードオフ** | 受け入れた妥協点 | 「graceful degradation パターンが使えなくなる」 |

### 2. 関連アイテムの特定

意思決定が影響するトレーサビリティチェーン上のアイテムを特定する。

```bash
# 変更されたファイルから逆引き
trace_query.py <dir> chain --file <path>

# UID が分かっている場合
trace_query.py <dir> chain <UID>
```

### 3. ADR の作成

```bash
doorstop_ops.py <dir> add -d ADR \
  -t "ADR本文（後述のテンプレートに従う）" \
  --header "判断の短い見出し" \
  -g <GROUP> \
  --links <関連アイテムUID...>
```

### 4. ADR 本文の記述

以下のセクション構成に従って `text` を記述する。
議論の経緯が分かるよう、**棄却された代替案とその理由**を必ず含める。

```markdown
## コンテキスト（背景）

この判断が必要になった背景。何が問題だったか。
ユーザーとの議論のきっかけや、外部からの指摘があればそれも記載する。

## 決定

採用した具体的な方針。何をどう変えるか。

## 結果（トレードオフ）

- **メリット**: 決定による利点
- **デメリット**: 受け入れた妥協点・制約

## 棄却された代替案

- **案X**: 概要。棄却理由
- **案Y**: 概要。棄却理由
```

### 5. レビューとステータス設定

```bash
# レビュー済みにする
doorstop_ops.py <dir> review <ADR_UID>
```

ステータスは通常 `accepted`（デフォルト）。
提案段階でユーザーの承認を待つ場合は `proposed` に設定する。

```bash
# 提案段階の場合
doorstop_ops.py <dir> update <ADR_UID> --status proposed
```

### 6. 既存 ADR の更新（判断を覆す場合）

既存の意思決定を覆す場合は、旧 ADR を `superseded` に更新してから新 ADR を作成する。

```bash
doorstop_ops.py <dir> update ADR001 --status superseded
doorstop_ops.py <dir> add -d ADR -t "新しい判断..." --links ADR001 SPEC001
```

### 7. 報告

```
ADR054 を作成しました。
  - 判断: SQLiteTaskDB のスキーマ初期化を RAII パターンに移行
  - 関連: SPEC007, IMPL007
  - ステータス: accepted
```

## エージェントへの指針

### いつ ADR を提案すべきか

以下のシグナルを会話中に検出した場合、ADR の作成をユーザーに提案する：

- ユーザーが「こっちの方がいい」「こうしよう」と方針を決定した
- 複数の選択肢を比較検討した議論が収束した
- 「なぜ」「どうして」の議論が深まり、非自明な判断に至った
- 既存の ADR に記録された判断と異なる方針を採用した
- 外部からのレビューや指摘に基づいて設計を変更した

### 提案の仕方

```
この意思決定を ADR に記録しますか？
- 判断: [1行要約]
- 代替案: [棄却した案の列挙]
```

ユーザーが同意した場合のみ作成する。不要と言われた場合は作成しない。
