write-adr

ADR の作成

現在のセッション中に行われた決定から、アーキテクチャ決定記録（ADR）を生成します。

ワークフローの概要

1. コンテキスト - リポジトリのコンテキストと既存の ADR を収集します
2. 抽出 - サブエージェントを使って会話から決定を分析します
3. 確認 - 選択できるよう、決定をユーザーに提示します
4. 作成 - サブエージェントを使って ADR を並行して生成します
5. 報告 - 作成したファイルとステータスを要約します
6. 検証 - 生成した ADR を完了の定義に照らして検証します

ゲート（客観的な合格条件）

合格条件を満たした場合にのみ次へ進みます。「内部で検証しました」では確認できません。

完了後	合格条件
ステップ 2（抽出）	サブエージェントの応答が、トップレベルに decisions 配列（空でも可）を持つ有効な JSON であること。空でない各項目には、id、title に加えて、context、decision、alternatives、rationale のいずれかが空でない文字列または空でない配列として少なくとも 1 つ含まれていること。解析に失敗した場合、または形式が正しくない場合は、ステップ 3 の前に抽出を再実行するか、ペイロードを修正すること。
ステップ 4（事前割り当て）	リポジトリのルートから python plugins/beagle-analysis/skills/adr-writing/scripts/next_adr_number.py --count N を実行すると、ちょうど N 行（1 行に 1 つの番号）が出力されること。ADR 作成ユニットを起動する前に、選択した各決定を出力行のいずれかに対応付けた書面の対応表（返信の下書きまたはメモ）があること。
ステップ 5（報告）	要約表に記載するすべてのファイルパスが、サブエージェントの完了出力から転記されていること（創作したものではないこと）。任意の抜き取り確認として、成功を示す前に各パスについて test -f <path> を実行できます。
ステップ 6（検証）	各 ADR パスについて、ファイルを開くと1 行目が --- であり、フロントマターが YAML として解析でき、status と date が存在し、本文が以下のステップ 6 の箇条書き項目（代替案の数、Good/Bad の結果）を満たしていること。

ステップ 1: コンテキストの収集

# Get current branch and recent commits
git branch --show-current
git log --oneline -5

# Check for existing ADRs
ls docs/adrs/ 2>/dev/null || echo "No ADR directory found"

# Count existing ADRs for numbering
find docs/adrs -name "*.md" 2>/dev/null | wc -l

このコンテキストは ADR 作成者が以下を行う際に役立ちます。

• ADR 内で関連するコミットを参照する
• すでに文書化されている決定について、ADR の重複を避ける
• 正しい連番を判断する

ステップ 2: 決定の抽出

現在の会話からアーキテクチャ上の決定を分析します。エージェントがサブエージェントに対応している場合は、抽出を 1 つのサブエージェントに依頼します。対応していない場合は、同じ抽出をインラインで実行します。出力は同一です。次の指示を使用します。

Load the **adr-decision-extraction** skill ([../adr-decision-extraction/SKILL.md](../adr-decision-extraction/SKILL.md)).

Analyze the conversation for decisions that warrant ADRs:
- Technology choices, architecture patterns, design trade-offs
- Rejected alternatives, significant implementation approaches

Return JSON:
{
  "decisions": [
    {
      "id": 1,
      "title": "Use PostgreSQL for primary datastore",
      "context": "Brief context about why this came up",
      "decision": "What was decided",
      "alternatives": ["What was considered but rejected"],
      "rationale": "Why this choice was made"
    }
  ]
}

サブエージェントが空の decisions 配列を返した場合は、メッセージ「このセッションではアーキテクチャ上の決定は検出されませんでした。」を表示してステップ 5 に進みます。

ゲート: ステップ 3 に進む前に、**ゲート（客観的な合格条件）**のステップ 2 の行を満たしてください。

ステップ 3: ユーザーへの確認

抽出した決定を詳細をすべて含めて表示してから、ユーザーに選択を求めます。

## Detected Decisions

### 1. Use PostgreSQL for primary datastore
**Confidence:** high

**Problem:** Need ACID transactions for financial records

**Decision:** PostgreSQL for user data storage

**Alternatives discussed:**
- MongoDB
- SQLite

**Rationale:** ACID compliance, team familiarity, mature ecosystem

**Source:** Discussion about database selection in planning phase

---

### 2. Implement event sourcing for audit trail
**Confidence:** medium

**Problem:** Compliance requires complete audit history

**Decision:** Event sourcing pattern for state changes

**Alternatives discussed:**
- Database triggers
- Application-level logging

**Rationale:** Immutable audit trail, temporal queries, debugging capability

**Source:** Compliance requirements discussion

---

## Selection

Which decisions should I write ADRs for?
- Enter numbers (e.g., "1,2" or "1-2"), "all", or "none" to skip

重要: 選択を求める前に、抽出結果に含まれる決定の詳細（問題、決定、代替案、根拠）を必ずすべて表示してください。タイトルとコンテキストだけに省略しないでください。

ユーザーの応答を解析します。

• "all" - すべての決定を処理します
• "none" または空 - メッセージ「ADR は作成されません。」を表示してスキップします
• "1,2" または "1-2" - 指定された決定を処理します

ステップ 4：ADR を作成する（並列）

サブエージェントを起動する前にADR 番号を事前に割り当て、番号の重複を防ぎます。

# Pre-allocate numbers for all confirmed decisions (from repository root)
# Example: If user selected 3 decisions
python plugins/beagle-analysis/skills/adr-writing/scripts/next_adr_number.py --count 3
# Output:
# 0003
# 0004
# 0005

サブエージェントを起動する前に、事前に割り当てた各番号を対応する決定に割り当てます。

ゲート： 最初の ADR 作成ユニットを起動する前に、**ゲート（客観的な合格条件）**のステップ 4 の行を満たしてください。

確認済みの決定ごとに、事前に割り当てた番号を使用して ADR 作成ユニットを実行します。エージェントがサブエージェントに対応している場合は、決定ごとに作成担当を 1 つ割り当てて並列に実行します。対応していない場合は、各 ADR を順番に作成します。出力は同じです。次の指示を使用します。

Load the **adr-writing** skill ([../adr-writing/SKILL.md](../adr-writing/SKILL.md)).

Write an ADR for this decision:
```json
{decision JSON}

重要：事前に割り当てた次の ADR 番号を使用してください：{assigned_number}

指示：

1. 追加のコンテキストを得るため、コードベースを調査します
2. docs/adrs/ に MADR 形式の ADR を作成します
3. 事前に割り当てた番号 {assigned_number} を使用します。next_adr_number.py は呼び出さないでください
4. ファイル名の形式：{assigned_number}-slugified-title.md
5. 作成したファイルのパスを返します

**Critical:** Pass the pre-allocated number to each writer unit. Writers must NOT call `next_adr_number.py` themselves - this causes duplicate numbers when running in parallel.

Wait for all writer units to complete before proceeding.

## Step 5: Report Results

**Gate:** Meet the Step 5 row in **Gates (objective pass conditions)** when building the summary (paths from subagent outputs; optional `test -f`).

Collect outputs from all subagents and present summary:

```markdown
## ADR Generation Complete

| File | Decision | Status |
|------|----------|--------|
| docs/adrs/0003-use-postgresql.md | Use PostgreSQL for primary datastore | Draft |

### Next Steps
- Review generated ADRs for accuracy
- Update status from "proposed" to "accepted" when finalized

### Gaps Requiring Investigation
- [List any decisions where subagent noted missing context]

処理した決定がない場合：

No ADRs were created. Run this command again after making architectural decisions.

ステップ 6：生成された ADR を検証する

作成した各 ADR について、完了の定義に照らして検証します。

## Verification Checklist

| ADR | E | C | A | D | R | Status |
|-----|---|---|---|---|---|--------|
| 0003-use-postgresql.md | ✓ | ✓ | ✓ | ⚠ | ✗ | Incomplete |

Legend: E=Evidence, C=Criteria, A=Agreement, D=Documentation, R=Realization

ゲート： 作成したすべての ADR について、**ゲート（客観的な合格条件）**のステップ 6 の行を満たしてください。

検証手順：

1. 生成された各 ADR ファイルを開きます
2. ファイル名が NNNN-slugified-title.md のパターンに従っていることを確認します
3. YAML フロントマターがファイルの先頭にあることを確認します：
   • ファイルは --- で始まる必要があります
   • status: draft（または有効なステータス）が含まれている必要があります
   • date: YYYY-MM-DD（実際の日付）が含まれている必要があります
   • タイトルの前に --- で終わっている必要があります
   • フロントマターがない場合は、直ちに追加します
4. [INVESTIGATE] プロンプトがないか確認します。これらは追加の対応が必要です
5. 少なくとも 2 つの代替案が記載されていることを確認します
6. 結果セクションに Good と Bad の項目が両方あることを確認します

不備がある場合：

• 不備が解消されるまで、ステータスは draft のままにします
• [INVESTIGATE] プロンプトを使用して、次回のフォローアップセッションで確認する内容を示します
• ステータスを accepted に変更する前に、関係者とのレビューを予定します

出力先

ADR は docs/adrs/ に作成します（adr-writing と同じ規則です）。ADR ディレクトリがない場合は、初期テンプレートレコード 0000-use-madr.md を作成してディレクトリを作成します。

MADR 形式のリファレンス

---
status: draft
date: YYYY-MM-DD
---

# {TITLE}

## Context and Problem Statement

{What is the issue motivating this decision?}

## Decision Drivers

* {driver 1}
* {driver 2}

## Decision Outcome

Chosen option: "{option}", because {reason}.

### Consequences

* Good, because {positive}
* Bad, because {negative}