doc-brd-fixer

doc-brd-fixer

目的

最新の監査レポートを読み取り、BRD に修正を適用します。これにより、 ../doc-brd-audit/SKILL.md と合格する BRD をつなぎ、監査↔修正のサイクルが 収束できるようにします。

レイヤー：1（BRD の品質改善）。 上流：BRD ドキュメント + .aidoc/audit/01_BRD-audit.md。 下流：修正済み BRD + BRD-NN.F_fix_report_vNNN.md。

使用するタイミング

doc-brd-audit が FAIL を返した後、監査 → 修正 → 監査のループの一環として使用します。 監査レポートなしでは使用しないでください（先に監査を実行してください）。また、 新しい BRD の作成には使用しないでください（../doc-brd/SKILL.md / ../doc-brd-autopilot/SKILL.md を使用してください）。

入力契約

.aidoc/audit/01_BRD-audit.md（.aidoc/ の来歴ティア）から最新の監査レポートを 取り込みます。編集前に BRD をバックアップしてください （tmp/backup/BRD-NN_<ts>/）。エラーが発生した場合は復元します。要素 ID の規則は ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md に、 構造のルールは ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml と README.md に従います。

修正モード

.aidoc/profile.yaml から review_mode を解決します。設定されていない場合は、 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md の優先順位チェーンに 従って、フレームワークのデフォルトである team にフォールバックします。同じ フォールバックは、その他の適応設定（section_toggles）にも適用されます。

チームモード（REVIEW_TEAM.md §Operations §Remediateに従う）

1. 監査レポート .aidoc/audit/01_BRD-audit.md を読み、さらに存在する場合は、統合担当の verdict.json とペルソナ別スロットを .aidoc/review/01_BRD/<BRD-id>/ から読みます（<BRD-id> は BRD-01 のような短い成果物 ID です）。

   • 阻害要因の件数とカバレッジの概要には、verdict.json を優先します。これは統合担当（agents/synthesizer.md）が書き出す決定論的な JSON です。
   • 構造化された指摘事項には、ペルソナ別スロットを優先します。安定した ID、優先度、場所、推奨事項が含まれています。
   • スロットと verdict.json は任意です。存在しない場合（たとえば、single_pass の実行で統合担当の出力が生成されなかった場合）は、監査レポートの「Findings」セクションを直接解析します。

2. 各指摘事項の担当レンズを特定します。 各阻害要因（P0 + P1）には、統合担当が簡略化した形式の personas 配列（verdict.json:findings[*].personas を参照）が含まれているか、レンズ別スロットのメンバーシップから推定できます。ディスパッチのルールは次のとおりです。

   • 単一レンズの指摘事項（ペルソナ 1 つ）：そのレンズをディスパッチします。
   • 複数レンズの指摘事項（ペルソナ 2 つ以上。たとえば、architect と business_analyst の矛盾）：記載されているすべてのレンズを並行してディスパッチします。それぞれが独自の <persona>.fix_<N>.json スロットに書き込みます。修正が受け入れられるのは、ディスパッチされたすべてのレンズが新たな P0/P1 を返さなかった場合のみです（いずれかのレンズで後退があれば、パッチを元に戻します）。
   • ペルソナなし／孤立した指摘事項（personas が空または欠落）：デフォルトの担当レビュアーとして、BRD クルーの作成者レンズ（REVIEW_CREWS.yaml に従い、BRD の場合は business_analyst）をディスパッチします。作成者レンズを使い、指摘事項をスキップしないことで、すべての阻害要因に少なくとも 1 回の検証を確実に行います。 P2/P3 は助言的な指摘事項です。レンズによる検証なしで決定論的に適用します。

   BRD のレンズ → エージェント対応表：

   レンズ	エージェント
   architect	aidoc-flow:solutions-architect
   business_analyst	aidoc-flow:requirements-analyst
   auditor	aidoc-flow:traceability-auditor
   chaos_engineer	aidoc-flow:chaos-engineer
   security_engineer	aidoc-flow:security-engineer

3. 阻害要因ごとにパッチを提案して適用します。 以下の修正フェーズ 0～7 でパッチの形式を説明します。カタログはどちらのモードでも同じです。既存の入力契約に従い、先にバックアップを作成します。

4. 非後退を検証します。 手順 2 で特定した責任レンズごとに、パッチ検証モードで Task サブエージェントを 1 つディスパッチします。subagent_type=<mapped agent>（上記の対応表を使用）、brief = パッチ適用済みの領域 + 元の指摘事項 + パッチの差分です。lens_score を算出する際、レンズは作成者による自己評価スコア（*_ready_score／*_score／readiness_score／audit_score）を読んだり、引用したり、重み付けに使ったりしてはなりません（REVIEW_TEAM.md GD-05）。出力 = 新しいペルソナ出力レコード（パッチ適用済みの領域に対する lens_score と、新たな指摘事項があればその指摘事項）。各レンズの出力を .aidoc/review/01_BRD/<BRD-id>/<persona>.fix_<N>.json に保存します（<N> は 1 から始まる連続した修正反復カウンターです）。複数レンズの指摘事項では、同じ <N> に対して責任レンズごとに 1 つのスロットファイルを生成します。

5. 後退を元に戻します。 いずれかのレンズがパッチに対する新たな P0/P1 を返した場合は、そのパッチを元に戻し、元の指摘事項に manual_required のフラグを設定します。後退する修正を、決して黙って適用したままにしないでください。

6. すべてのパッチの検証後に、統合担当を 1 回ディスパッチします （subagent_type=aidoc-flow:synthesizer）。統一された修正レポートを出力させます。Fixes Applied テーブルと Validation Slots インデックスの両方を含む .aidoc/remediation/01_BRD-fix.md を保存します。

single_pass モード（フォールバック）

Phase 0～7を直接、単独で適用します。レンズ検証は行いません。従来どおりの動作を維持します。プロファイルで指定されている場合、Task サブエージェントのディスパッチが利用できない場合、またはスロットが存在しない場合に必要です。

どちらのモードでも、P2／P3の助言的な指摘はレンズ検証なしで適用します。チームモードでパッチ検証ループを通るのは、ブロッキング指摘（P0／P1）のみです。

Sagaとの連携

doc-brd-autopilotから（または直接）呼び出された場合、このスキルは${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.mdに従って、.aidoc/review/01_BRD/<BRD-id>/saga.jsonのSagaジャーナルを読み取り、更新します。修正ツールはSagaの修復ステージとして動作します。パッチ検証中にブランチをBRANCH_COMPENSATINGへ遷移させ、その後、（検証済みなら）BRANCH_COMPLETEDへ、または（リグレッションが検出された場合は）BRANCH_FAILEDへ戻します。

エントリー時

エントリー時に、修正ツールの開始エポックを書き込みます。

Bash: mkdir -p .aidoc/review/01_BRD/<BRD-id>/ && date +%s > .aidoc/review/01_BRD/<BRD-id>/.skill-start.fixer

.aidoc/review/01_BRD/<BRD-id>/saga.jsonが存在する場合は、読み取ります。現在のSagaのstatusがFANIN_REDUCED（監査後）またはBRANCH_FAILED（修正ツールによる前回のリグレッション後の再実行）であることを検証します。statusがそれ以外の場合は、警告を記録して処理を続行します。

マルチレンズ検証中（チームモード）

レンズ検証が必要な各ブロッキング指摘（P0／P1）について、次の処理を行います。

1. 担当するレンズ検証ツールをディスパッチする前に、指摘のpersonas[]リストにある各レンズについて、遷移を追加します。 {"ts": "<now>", "from": "BRANCH_COMPLETED", "to": "BRANCH_COMPENSATING", "scope": "branch:<lens>"} branches[<lens>].statusを"BRANCH_COMPENSATING"に更新します。compensation_actions[]に次のエントリーを追加します。 {"ts": "<now>", "branch": "<lens>", "reason": "<finding_id>: <message>", "action": "retry"}。
2. 検証用のTaskサブエージェントが戻った後：
   • パッチが検証に合格した場合（リグレッションなし）：BRANCH_COMPLETEDへ遷移させます。compensation_actions[]の最後のエントリーを検証結果で更新します。
   • パッチでリグレッションが発生した場合（レンズがパッチ適用範囲内に新たなP0／P1を指摘）：BRANCH_FAILEDへ遷移させます。compensation_actions[]の最後のエントリーのactionを"escalate"に設定します。指摘はmanual_requiredになります。

サーキット遮断チェックポイント（マルチレンズ検証のディスパッチ間）

REVIEW_SAGA.md §「サーキット遮断ポリシー」に従い、修正ツールのチェックポイント境界はマルチレンズ検証のディスパッチ間です（各ブロッキング指摘に対するレンズごとの検証が1つの境界です）。次の検証をディスパッチする前に、次の処理を行います。

Bash: echo $(( $(date +%s) - $(cat .aidoc/review/01_BRD/<BRD-id>/.skill-start.fixer) ))

経過時間がSOFT_DEADLINE（1500s）を超えている場合：

• 遷移を追加します。 {"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "PARTIAL_TIMEOUT", "scope": "run"}。
• Sagaのstatusを"PARTIAL_TIMEOUT"に設定します。完了済みの検証はすべて保持します（そのfix_N.jsonスロットは永続化されます）。再開時に残りの検証を続けられるよう、current_phase: "fixer"に設定します。
• updated_atを更新します。saga.jsonを書き込みます。正常終了します。

残りの検証は、doc-brd-autopilotの§3.4の再開ロジックに従い、次回の呼び出し時に再開されます。

すべてのブロッキング指摘へのパッチ検証が完了した後

• 遷移を追加します。 {"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "BRANCH_COMPLETED", "scope": "run"}（実行レベル：修正ツールの処理が完了）。
• Sagaのstatusを"BRANCH_COMPLETED"に更新します（autopilotの次のフェーズはre-reviewになります）。
• updated_atを更新します。saga.jsonを書き込みます。

単独で呼び出された場合（エントリー時にsaga.jsonがない場合）

.aidoc/review/01_BRD/<BRD-id>/saga.jsonが存在しない場合（ユーザーがautopilotループの外で/aidoc-flow:doc-brd-fixerを直接実行した場合）、完全なSagaスキーマを初期化しないでください。saga.json not present; running fixer without saga journal (standalone mode)と記録します。通常どおり修正フェーズを実行し、修正レポートを書き込みます。すべてのsaga.json遷移を省略します。スキルの直接呼び出しとの後方互換性を維持します。

single_passモードで呼び出された場合

review_mode: single_passが有効な場合、修正ツールはレンズ検証を行わずにパッチを決定論的に適用し、saga.jsonへの書き込みも行いません。既存の動作を維持します。

ブレークサーキットポリシー

${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md §「ブレークサーキットポリシー」に従い、このスキルは1つのチェックポイント境界、つまり （REVIEW_SAGA.md の表に従った）複数レンズ検証のディスパッチ間で、 経過した実時間を確認します。SOFT_DEADLINE は1500秒です （ORCHESTRATOR_TIMEOUT=1800s から300秒のバッファを差し引いた値）。

ソフトデッドラインを超えた場合は、上記の§「ブレークサーキットチェックポイント」に従って、 saga の status: "PARTIAL_TIMEOUT" で正常に終了します。 修正担当の部分的な進捗（すでに書き込まれた fix_N.json スロット）は 保持されます。再開された呼び出しは、ブレークサーキットが作動した時点から続行します。

修正フェーズ

順番に実行してください。後続のフェーズは、それ以前のフェーズが成功していることを前提とします。

フェーズ	対象範囲	代表的なアクション
0 — 構造	ネストされたフォルダの規則	BRD を docs/01_BRD/BRD-NN_{slug}/ に移動する；フォルダ名を ID に合わせて変更する；移動後に相対リンクを修正する
1 — ファイル不足	参照先が存在しないファイル	テンプレートから用語集／GAP／参照用プレースホルダーを作成する
2 — リンク	壊れたパス／絶対パス	相対パスを再計算する；絶対パスを相対パスに変換する
3 — 要素 ID	レガシー／無効な ID	BRD.NN.SS.xxxx（セクション番号＋コンテンツハッシュ）を再導出する；レガシーな BRD.NN.xxxx、数値のタイプコード、FR-XXX／BO-XXX のプレフィックスを削除する
4 — コンテンツ	プレースホルダー、サブセクション不足	テンプレートの日付を埋める；MVP サブセクションの見出しをその場で標準化する；安全な同階層項目の番号を振り直す；[TODO]／[TBD] による手動補完箇所を明示する
5 — 参照	トレーサビリティ	不足している @ref: タグを追加する；BRD 間のパスを修正する；トレーサビリティマトリクスを更新する
6 — 上流	メタデータ＋ドリフト	deliverable_type／document_type／upstream_mode を修正する；upstream_mode: "ref" の場合は、段階的なドリフトマージ（以下を参照）を適用する
7 — スタイル	STY01 禁止フレーズ、STY02/03 の長すぎる文章、FM01 フロントマターの不一致	埋め草表現を置き換える（in order to → to；the fact that、it should be noted、please note、as a matter of fact を削除する）；指摘された最上級表現（amazing、seamless、cutting-edge、state-of-the-art）を置き換える；1つのセクションに禁止フレーズが3つ以上ある段落を箇条書きにまとめる；フロントマター ↔ 文書管理情報 ↔ 改訂履歴の行を整合させる（フロントマターを正として反映する）；STY02/03 — 300語を超えるセクションは、最初に現れる自然な小見出しの位置で自動的に分割するか、manual_required とマークする。準拠基準：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

要素 ID の再導出： BRD.{doc_id}.{section_id}.{hash}。ここで SHA-256 を計算しないでください。ジェネレーターを呼び出してください：python -m sdd_doc_lint.rehash --compute --doc-id NN --section-id SS --title T --description D （衝突時は --length 8）。既存の ID が不正な形式でない限り、そのまま保持してください。有効な ID を再導出すると、後続のすべての引用が壊れます。準拠基準：framework/governance/ID_NAMING_STANDARDS.md。 文書レベルの参照（SPEC-NN、ADR-NN、IPLAN-NN）はダッシュ形式のままにします。

段階的な上流ドリフト（upstream_mode: "ref" の場合のみ）：変更が5%未満 → ティア1の自動マージ（パッチバンプ）；5～15% → ティア2の自動マージ＋詳細な変更履歴 （マイナーバンプ）；15%超 → ティア3で現在の文書をアーカイブし、自動操縦で再生成する（メジャーバンプ）。上流で削除された内容は決して削除しないでください。[DEPRECATED] とマークし、トレーサビリティのために保持します。 結果を .drift_cache.json に記録します。

信頼度の分類

適用した修正すべてにタグを付け、件数をレポートに記載します：

信頼度	意味
auto-safe	決定論的で、意味上のリスクが低い（リンク／パス、見出しの標準化、ID 変換）
auto-assisted	部分的な仮定を伴うテンプレートの挿入（ひな形を用意した表／サブセクション）
manual-required	ドメイン固有の内容を推測できない（未解決の TODO／TBD、戦略上の根拠）

コンテンツ保持ルール

• 既存のビジネスコンテンツは削除しないでください。テンプレートブロックを挿入するのは、セクションが存在しない場合、または最小構成を満たしていない場合に限ります。
• 同等の見出しはセクションを重複させず、該当箇所で標準化してください。
• 番号を振り直すのは同じセクションファイル内に限ります。相互参照アンカーが壊れる場合は報告してください。

修正レポートの形式

テーブル内のパイプ文字のエスケープ（MD056）

シェルのパイプを含むコードスパン（例：`docker compose ps | grep 'Up'`）を含む Markdown のテーブルセルを出力すると、コードスパン内のエスケープされていない | が Markdownlint によって列区切りとして解析され、MD056（列数の不一致）が発生します。修正方法は 2 つあります。

• 推奨： コードスパン内のパイプを \| としてエスケープします。Markdown ビューアーでは | と表示されますが、テーブルは壊れません。 行の例：| OP-02 | ... | `docker compose ps \| grep 'Up'` | ... |
• 代替方法： コードスパンをテーブルセルの外に移動し、テーブルの下で脚注または段落として参照します。セルには「シェルの準備完了ゲート（下記を参照）」のような通常のテキストを記載します。

テーブルセル内にシェルのパイプを含むコードスパンを出力するすべてのレポート行に適用してください。MD056 を引き起こすカスケード出力は SKILL のバグであり、Markdownlint の過度な厳格さが原因ではありません。リンターのチェックを無視するのではなく、ここで修正してください。

BRD-NN.F_fix_report_vNNN.md を作成し、次を含めてください。概要（問題の件数／修正済み／未対応、作成／変更したファイル） · 適用した修正（コード、問題、修正内容、ファイル、信頼度） · 手動レビュー待ち · 修正後の検証（スコア／エラー／警告の修正前→修正後） · クリーンアップの概要（置き換えられた修正レポートの削除） · 次のステップ（doc-brd-audit を再実行）。スコアがしきい値以上になるか、最大反復回数に達するまで繰り返してください。

適用

修正を適用する前に、プロジェクトの適用プロファイル（.aidoc/profile.yaml）を読み込んでください。 section_toggles を遵守してください。プロジェクトで無効にされた任意のセクションを再導入しないでください。不明なキー、または対象範囲外のキーは無視してください。 規範：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

関連リソース

• 監査（入力）：../doc-brd-audit/SKILL.md · 作成：../doc-brd/SKILL.md
• オーケストレーション：../doc-brd-autopilot/SKILL.md · ID：../doc-naming/SKILL.md
• 規範：${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md