adr-backfill

adr-backfill

過去に下されたものの、記録されなかったアーキテクチャ上の決定を遡って記録します。対象となるのは通常、/doc-audit の BACKFILL-ADR 行、または過去の変更を ADR にすべきだったとユーザーが気づいたケースです。adr-drafting と比べて条件を緩和して運用します（決定者を特定できない場合や、代替案を再構成できない場合があります）が、記録の誠実さについてはより厳格にします。バックフィル ADR であることを明確に示し、後の読者が同時期に作成された記録だと誤認しないようにする必要があります。

このスキルを使う場面

• /doc-audit で BACKFILL-ADR の候補行が見つかり、ユーザーがそれを記録したい場合。
• ユーザーが、現在コードベースに影響が見られる変更について、過去形で決定を語る場合 — 「何年も前に決めた」、「当時は」、「自分が来る前に」、*「記録に残していなかった」*など。
• コードの考古学的調査で、対応する決定記録のない移行、ベンダーの削除、サブシステムの廃止が見つかった場合。

このスキルを使わない場面

• 決定が現在進行中、または検討中の場合 — 代わりに adr-drafting を使います。
• 決定がすでに何らかの形で記録されている場合 — 既存の記録を改善するために adr-critique を使います。
• reconstruction-confidence が low（再構成できるのが 何をしたか だけで、なぜそうしたか は不明）の場合 — 起草を拒否し、open-questions.md に誘導します。
• 変更にアーキテクチャ上の重要性がない場合 — _shared/adr-is-backfillable.md § 2 を参照してください。doc-diagnostic の代替案カタログを通じて振り分けます。

入力

• 必須： 独立した証拠ロケーターが少なくとも 2 つあること（_shared/adr-is-backfillable.md § 3 を参照）。例：コミット SHA と移行ファイル、移行ファイルと削除済みのマニフェストエントリ、削除済みモジュールと廃止された機能フラグのコミット。
• 必須： 影響を受けるアーキテクチャ特性について、測定可能なシグナルがあること（_shared/adr-is-backfillable.md § 4 を参照）。
• 任意： decision、evidence-locator、ASR-test-result、reconstruction-confidence、suggested-status フィールドを含む、/doc-audit の BACKFILL-ADR 行。ある場合は、最初の概要として使用します。

拒否の条件

このスキルは、次の場合に起草を拒否します。

• _shared/adr-is-backfillable.md の適格性セルフチェックで、項目 1～3 または 5 が不合格となる（証拠がない、ASR 上の重要性がない、証拠ロケーターが 1 つしかない、またはすでに記録されている）。
• reconstruction-confidence が low である — なぜそうしたか を捏造することになるためです。open-questions.md に誘導します。
• 影響を受けるアーキテクチャ特性について、測定可能なシグナルを挙げられない。
• ユーザーがバックフィル ADR を同時期に作成された記録のように見せたい（誠実さを示す条項を付けない）と望む場合。この条項は必須です。

基本的な運用ルール

1 回のメッセージで、質問または手順を 1 つ以上提示してはいけません。 adr-drafting の「1 ターンにつき質問 1 つ」の規律を引き継ぎます。バックフィルは、先に向けた起草と同じかそれ以上に内容を詰め込みやすいため、規律を緩めるのではなく、より厳格にします。

4 つのフェーズ

フェーズ 1 — 適格性と証拠

候補に対して、_shared/adr-is-backfillable.md の 7 項目の適格性セルフチェックを実施します。項目を 1 つずつ確認してください。いずれかが不合格なら中止します。

• 項目 1～3 または 5 が不合格 → 起草を拒否し、どの証拠が不足しているかを説明します。
• 項目 4 が不合格（測定可能なシグナルがない） → open-questions.md に誘導します。
• 項目 6 が不合格（確信度が low） → 判定を引き上げるために必要な証拠を添えて、open-questions.md に誘導します。
• 項目 7 が不合格（決定者を特定できず、unrecoverable ともマークされていない） → unrecoverable マーカーを使うか、さらに調査を続けるかを一度だけ尋ねます。

対話の中で、2 つのロケーターを引用し、ユーザーに示して証拠を確認します。誤った資料を指していた場合に修正できるようにしてください。ユーザーが証拠を正しいと認めるまで、フェーズ 2 に進んではいけません。

フェーズ 2 — 過去のコンテキストの再構築（可能な範囲で）

ADR の各セクションについて、再構築できる内容を集め、曖昧にせず不足している情報を明示してください。

セクション	再構築の方法
コンテキスト（背景となる要因）	コミットメッセージ、PR の説明、チケットへのリンク、削除された README の内容、廃止されたランブックを確認します。各情報源を引用してください。背景となる要因を再構築できない場合は、「決定時点の背景となる要因は、入手可能な証拠から再構築できませんでした。」と記載してください。捏造してはいけません。
決定	何を決定したかです。ほとんどの場合、リリース済みの変更から再構築できます。今後作成する ADR と同様に、現在形の能動態で記載します。
代替案	再構築が最も難しいことが多い項目です。元の代替案が PR のレビューコメント、コミット履歴、当時の RFC で確認できる場合は、それらを引用してください。確認できない場合は、誠実さを示す条項でその不足を補います。
結果（良い点／悪い点）	現在のコードベースで観察できる影響から再構築します。「14k 行のコードを削除」は観察可能ですが、「開発者の士気を高めた」は観察できません。
決定者	コミットの作成者、PR のレビュアー、または明示的な帰属情報から特定した人名を記載するか、文字どおりのトークン unrecoverable を記載します。決して捏造してはいけません。

フェーズ 3 — 誠実さを示す条項を含めて下書きする（必須）

すべてのバックフィル ADR には、本文の冒頭付近（タイトルの後、コンテキストの前）に、文言を一字一句変えずに誠実さを示す条項を含める必要があります。必須の文言、必須フィールド、末尾の句読点、拒否条件については references/honesty-clause.md を確認してください。下書きの前に必ず読んでください。

この条項は、後の読者がバックフィルを当時の記録と誤認しないようにするためのものです。この条項を削除したり、表現を弱めたりすると、批評対象のフラグが立ちます（adr-critique の監査チェックリストを参照）。

フェーズ 4 — 保存する

adr-drafting と同じ保存手順に従います。

1. まず ADR Explorer が認識しやすいディレクトリを検索します（docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md）。また、旧形式の architecture/decisions/ も確認しますが、ADR Explorer のルートをカスタム設定する必要がある場合があります。最初に見つかった既存のディレクトリを使用します。見つからない場合は docs/adr/ を作成します。
2. 自動採番します。既存の ADR を読み込み、最大番号に 1 を加え、4 桁のゼロ埋めにします。**バックフィル ADR には、過去の番号ではなく、次に利用可能な番号を割り当てます。**番号は決定順ではなく、作成順を示します。元の決定日はファイル内に記載します（frontmatter を参照）。番号は今付けたものです。
3. ファイル名は NNNN-kebab-imperative-title.md とします。
4. 誠実さを示す条項と、バックフィル専用の frontmatter（下記のテンプレートを参照）を記述してファイルを作成します。
5. 決定ログの README.md インデックスを更新し、該当する行に (backfilled YYYY-MM-DD) を付けます。

バックフィル専用の frontmatter

---
title: "<imperative verb phrase>"
status: accepted                   # or deprecated if reversed; keep status ADR Explorer-compatible
date: <original decision date if known, else first-evidence date in ISO 8601>
backfilled-on: YYYY-MM-DD          # today
deciders:
  - <named human, or unrecoverable>
evidence:                          # at least two locators
  - <commit SHA / file path / manifest line>
  - <commit SHA / file path / manifest line>
reconstruction-confidence: high | medium
asr-characteristic: <latency | cost | availability | security | maintainability | operability | portability | ...>
asr-signal: "<measurable signal -- e.g., removed 14k LOC and one vendor dependency>"
tags: [backfill]
---

その後のリリース済み変更によって決定が覆されている場合は、status: deprecated を設定し、覆したコミットまたは移行を evidence: と誠実さを示す条項または注記に記載します。覆された後でも、過去の決定は重要なのでバックフィル ADR を記録します。ただし、ステータスは引き続き ADR Explorer と互換性のあるものにします。

ステータスの規約

ステータス	使用する状況
accepted	決定が現在も有効な場合。デフォルトです。
deprecated	その後のリリース済み変更によって元の決定が覆された場合。覆したことを示す証拠を引用してください。

バックフィル ADR では proposed や rfc は使用しません。バックフィルとは、定義上、すでにリリース済みの決定を記録するものです。バックフィルであることは tags: [backfill]、backfilled-on、証拠フィールド、必須の誠実さを示す条項で明示してください。status によって示してはいけません。

拒否：ユーザーが誠実性条項の削除を求めた場合

誠実性条項は、バックフィル ADR における唯一の譲れない要素です。ユーザーが削除したり、表現を弱めたり、脚注に隠したりするよう求めた場合は、拒否してください。条項のないバックフィルは、当時作成された記録のように見え、意思決定ログを知らぬ間に損なうことを説明してください。将来の読者には、その根拠がその場で記録されたものではなく、後から再構成されたものだと見分ける方法がありません。条項は本文に残してください。

adr-critique はこれを独立して適用します。tags: [backfill] または backfilled-on があり、本文に誠実性条項がない記録は、監査チェックリストでフラグが立てられます。

引き継ぎ

adr-backfill は、他のスキルに自動的には連鎖しません。バックフィル記録の保存後、ユーザーは次の操作を選択できます。

• 新しい記録に対して adr-critique を実行し、表現を引き締めます（特に reconstruction-confidence が medium だった場合）。
• c4-model を実行して、意思決定後のシステム構成を反映した Context / Container ビューを追加します（任意）。
• open-questions.md を更新し、バックフィルによって解決された保留中の質問をクローズします。

いずれも強制ではありません。スキルのトリガーによる、控えめな引き継ぎのみです。

参考資料

• references/honesty-clause.md — Phase 3 の誠実性条項に関する正式な仕様（形式、必須フィールド、文末の句読点、拒否条件）。唯一の信頼できる情報源です。adr-critique も同じファイルを読み込みます。
• ../_shared/adr-is-backfillable.md — 適格性を自己確認する7項目のチェックリスト（Phase 1 で使用）
• ../_shared/adr-is-not.md — 前向き ADR と同様に、バックフィル ADR にも適用されます（チュートリアル、実装ガイド、マーケティング、曖昧な表現、長文による水増しは不可）
• ../doc-diagnostic/references/audit-procedure.md — このスキルに渡される BACKFILL-ADR 行のスキーマを定義します
• adr-drafting スキル — その場での意思決定に対応する、前向きのドラフト作成スキル
• adr-critique スキル — 保存済みのバックフィル記録を後から引き締めるためのスキル
• doc-diagnostic スキル — ASR の定義と代替案カタログのためのスキル