rework: 手戻りの構造化プロトコル

目的: 「後から仕様の問題が分かってやり直し」を、場当たりの修正ではなく 上流から順に直し、影響範囲を機械的に列挙し、回帰ガード付きで最小修正する。

手順

1. 問題の層を特定する

発覚した問題が本当はどの工程の誤りかを先に確定する (症状の層で直さない):

2. 上流の文書を先に直す

コードを触る前に、該当する requirements.md / spec.md / design.md を修正する。

• 内容の改訂は ~~取り消し線~~ + 「変更 (YYYY-MM-DD): 理由」で痕跡を残す (同じ検討を繰り返さないため。設計判断の変更は ADR を追記)
• ID ごとの撤回・移管は取り消し線を使わず、本文を削除して文書末尾の 退役台帳へ 1 行 (spec-dev SKILL.md の「撤回・移管 — 退役台帳」。 履歴は git が持ち、再提案の防止は台帳の 1 行が担う)
• trace ゲート導入済みのプロジェクトでは、上流文書の修正とテスト側の ID 帳簿 (T の追加・S↔T 表・退役台帳) を同じコミットにする。S の受入条件とそれを 確かめる T は 1 つの宣言の両面で、matrix はこの 2 つを別々に動かさないための ゲート。テストはこの時点で落ちてよい — 実装前に落ちる証拠が履歴に残るのは G4 の要求どおり。コミットメッセージに「tests fail by design; implementation follows」と明記し、実装は次のコミットで行う (文書+テスト+実装を 1 コミットに 混ぜると、実装だけの巻き戻しができなくなる)
• 直した ID の 1 段上を読み直す (S を直したら実現元の R、D を直したら S)。 矛盾がないことを確認してから下流へ進む — trace-matrix は ID の有無しか 見ないので、意味のズレはここでしか捕まらない
• 直した ID を前提にしている下流も読み直す (D-02 を直したら、同じ design.md の D-03 以降を通しで)。手順 3 の grep では足りない — 下流は 上流を名指しせずに前提だけ受け継ぐので、ID は本文に現れない。実例では 旧前提の上に立つ下流が「書いてあるとおり作ると壊れる」状態で 1 日残り、 その ID が grep に当たるようになったのは訂正を書き込んだ後だった (= grep で見つかるのは直し終わったものだけ)。矛盾があれば手順 3 の 影響表に載せる。ここで気づかないと、影響表には最初から載らない
• 文書がないプロジェクトの場合、最低限「何が誤りで何に変えるか」のメモを作ってから進む

3. 影響範囲を列挙する

変更した ID から下流をたどる:

grep -rn "R-03\|S-05" docs/ notes/          # 文書間の参照
grep -rn "S-05\|D-02" --include=*.c --include=*.h --include=*.go -r src/ test/
git log --oneline --grep="D-02"              # 関連コミット

トレース ID がない (spec-dev 以前の) 資産は、シンボル名・キーワードで代用し、 Serena MCP や LSP があれば参照検索を使う。

結果を影響表にする:

4. 最小修正計画を提示し、承認を得る

• 「作り直す範囲」と「生かす範囲」を明示する。全部作り直しを既定にしない
• 生かす範囲については「なぜ影響を受けないか」を 1 行で言う
• この計画のユーザー承認を得てからコード修正に入る

5. 回帰ガード付きで修正する

fix-loop Skill のプロトコルで実施する:

• ガードテストセット = 影響表に挙がったテスト + その周辺の既存テスト
• ベースライン取得 → 1 変更 1 検証 → 台帳記録
• 影響表の項目を 1 つずつ消し込む (台帳と対応させる)

6. 終了処理

• R↔S↔D↔T の対応表が新しい内容で整合しているか再確認する
• 「なぜこの手戻りが起きたか」を 1 行で要件インタビュー項目 (spec-dev フェーズ 0) に 昇格できないか検討し、できるならユーザーに提案する (同じ手戻りの再発防止)

ルール

• 文書・コードの削除やブランチ操作など破壊的な操作は必ず事前確認する
• 影響範囲が 3 ファイル以下で層が実装のみなら、このプロトコルは過剰。fix-loop だけで進めてよい