doc-prd-fixer

doc-prd-fixer

目的

最新の監査レポートを読み取り、PRD に修正を適用して、 ../doc-prd-audit/SKILL.md と合格する PRD の間をつなぎ、 監査↔修正のサイクルを収束させます。

レイヤー：2（PRD 品質改善）。 上流：PRD ドキュメント + .aidoc/audit/02_PRD-audit.md。 下流：修正済み PRD + PRD-NN.F_fix_report_vNNN.md。

使用するタイミング

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

入力仕様

.aidoc/audit/02_PRD-audit.md レポートを読み込みます。編集前に PRD を バックアップし（tmp/backup/PRD-NN_<ts>/）、エラー時は復元します。要素 ID の規則は ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md に、構造規則は ${CLAUDE_PLUGIN_ROOT}/framework/layers/02_PRD/PRD-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/02_PRD-audit.md を読み、さらに存在する場合は、統合担当の verdict.json とペルソナごとのスロットを .aidoc/review/02_PRD/<PRD-id>/ で確認します（<PRD-id> は PRD-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 と product_owner の矛盾）：記載されたすべてのレンズに並列で振り分けます。各レンズは個別の <persona>.fix_<N>.json スロットに書き込みます。修正が受け入れられるのは、振り分けられたすべてのレンズから新たな P0/P1 が返されなかった場合のみです（いずれかのレンズで後退があれば、パッチを元に戻します）。
   • ペルソナなし／孤立した指摘（personas が空または存在しない）：デフォルトの担当レビューアーとして、PRD クルーの作成者レンズ（REVIEW_CREWS.yaml に従い、BRD の場合は product_owner）に振り分けます。スキップせず作成者レンズにフォールバックすることで、すべてのブロッキング指摘に少なくとも 1 回の検証を行います。 P2/P3 は助言的な指摘のため、レンズによる検証なしで決定論的に適用します。

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

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

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

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

5. 後退を元に戻します。 いずれかのレンズがパッチに対して新たな P0/P1 を返した場合、そのパッチを元に戻し、元の指摘に manual_required のフラグを付けます。後退を招く修正を黙って残してはなりません。

6. すべてのパッチを検証した後、統合レポートを出力するために統合担当を 1 回だけ振り分けます（subagent_type=aidoc-flow:synthesizer）。.aidoc/remediation/02_PRD-fix.md に Fixes Applied テーブルと Validation Slots インデックスの両方を保存します。

single_pass mode（フォールバック）

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

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

Sagaとの連携

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

開始時

開始時に、修正処理の開始時刻（エポック）を書き込みます。

Bash: mkdir -p .aidoc/review/02_PRD/<PRD-id>/ && date +%s > .aidoc/review/02_PRD/<PRD-id>/.skill-start.fixer

.aidoc/review/02_PRD/<PRD-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/02_PRD/<PRD-id>/.skill-start.fixer) ))

経過時間がSOFT_DEADLINE（1500秒）を超えた場合：

• 遷移を追加します。{"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-prd-autopilotの§3.4の再開ロジックに従って再開されます。

ブロッキング指摘に対するすべてのパッチの検証後

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

スタンドアロンで呼び出された場合（開始時にsaga.jsonがない場合）

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

single_pass modeで呼び出された場合

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

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

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

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

修正フェーズ

以下の順に実行します。後続のフェーズは、先行フェーズが成功していることを前提とします。

フェーズ	対象範囲	代表的な操作
0 — 構造	入れ子フォルダーのルール	PRD を docs/02_PRD/PRD-NN_{slug}/ に移動する。フォルダー名を ID と一致させる。移動後に相対リンクの ../01_BRD/ → ../../01_BRD/ を修正する
1 — ファイルの欠落	参照先が存在しないファイル	テンプレートから用語集／付録／参照ファイルのプレースホルダーを作成する
2 — リンク	リンク切れ／絶対パス	相対パスを再計算する。絶対パスを相対パスに変換する
3 — 要素 ID	旧式／無効な ID	PRD.NN.SS.xxxx（セクション番号 + コンテンツハッシュ）を再導出する。旧式の PRD.NN.xxxx、FR-XXX／US-XXX／AC-XXX／F-XXX のプレフィックスを削除する。SS と所属セクションの不一致を修正する
4 — コンテンツ	プレースホルダー、サブセクションの欠落	テンプレートの日付を入力する。§10／§14／§8 の構成をその場に作成する。[TODO]／[TBD] は手作業での完了が必要であることを示すために付ける
5 — 参照	トレーサビリティ	不足している @brd:／@prd: タグを追加する。PRD 間のパスを修正する。トレーサビリティマトリクスと親 BRD の下流エントリーを更新する
6 — 上流	メタデータ + ドリフト	deliverable_type／document_type を修正する。段階的な BRD ドリフトのマージ（以下）を適用する
7 — スタイル	STY01 禁止フレーズ、STY02/03 の長すぎる文章、FM01 のフロントマター不一致	埋め草表現を置き換える（in order to → to、the fact that、it should be noted、please note を削除する）。フラグが付いた最上級表現を置き換える。1つのセクションに禁止フレーズが 3 つ以上ある段落は箇条書きにする。フロントマターと Document Control の行を一致させる。STY02/03 — 300 語を超えるセクションは、最初の自然な小見出しで自動的に分割するか、manual_required としてマークする。準拠基準：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

要素 ID の再導出： PRD.{doc_id}.{section_id}.{hash} — セクション内で重複しない安定した 4 桁の 16 進数識別子を割り当てます（HASH01）。衝突した場合は 8 桁まで拡張します。ここで SHA-256 を計算してはいけません。ハッシュ形式は、決定論的なツールの処理によって生成される正準化の目標値であり、バイト単位で正確なフィールド抽出が定義されているのは BRD §7 のみです（PRD では Phase 2+）。有効な既存 ID は保持してください。再導出すると、下流の引用がすべて壊れます。 準拠基準：framework/governance/ID_NAMING_STANDARDS.md。section_id = 要素が存在するセクションです。文書レベルの参照（SPEC-NN、ADR-NN、IPLAN-NN）はハイフン形式のままにします。

段階的な上流ドリフト（BRD ソース）：変更が 5% 未満 → Tier 1 自動マージ（パッチバンプ）。5–15% → Tier 2 自動マージ + 詳細な変更履歴（マイナーバンプ）。15% 超 → Tier 3 現行版をアーカイブ + オートパイロットで再生成（メジャーバンプ）。上流で削除されたコンテンツは決して削除せず、[DEPRECATED] とマークしてトレーサビリティのために保持します。結果を .drift_cache.json に記録します。

信頼度の分類

適用したすべての修正にタグを付け、レポートに件数を示します。

信頼度	意味
auto-safe	決定論的で、意味的なリスクが低い（リンク／パス、ヘッダーの正規化、ID 変換）
auto-assisted	部分的な仮定を伴うテンプレート挿入（構成したテーブル／サブセクション）
manual-required	ドメイン固有のコンテンツを推測できない（未解決の TODO/TBD、§10 のメッセージング、ペルソナの詳細）

コンテンツ保持ルール

• 既存のプロダクトコンテンツは決して削除しないでください。テンプレートブロックを挿入するのは、セクションが欠けている場合、または最小構成を満たしていない場合に限ります。
• 同等の見出しは、セクションを重複させず、その場で標準化してください。
• 番号を振り直すのは同じセクションファイル内に限り、相互参照のアンカーが壊れる場合はその旨を報告してください。
• 図の契約に関する指摘では、図の宣言と Mermaid ブロックのみを編集してください。要件の内容には決して手を加えないでください。

修正レポートの形式

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

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

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

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

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

適応

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

関連リソース

• 監査（入力）：../doc-prd-audit/SKILL.md · 作成：../doc-prd/SKILL.md
• オーケストレーション：../doc-prd-autopilot/SKILL.md · ID：../doc-naming/SKILL.md
• 権限の根拠：${CLAUDE_PLUGIN_ROOT}/framework/layers/02_PRD/PRD-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md