doc-quality-gate

name	doc-quality-gate
description	ドキュメント品質ゲート — Critical/High が 0 件になるまでレビュー→修正を自動反復。Use when: 仕様書品質の自動向上、設計書の品質ゲート通過、ドキュメント品質の完全自動化
argument-hint	対象ドキュメント名（例: spec, api-gateway-design, full）

doc-quality-gate — ドキュメント品質ゲート Skill

目的

指定ドキュメントに対して orchest-doc-review Agent によるレビュー → 自動修正 → 再レビュー のサイクルを、 Critical = 0 かつ High = 0 の品質基準を満たすまで自動反復する。

人間の介入なしに設計書・仕様書の品質を自動的に引き上げる「品質ゲート」として機能する。

使用場面

• 仕様書（spec.md）の品質を自動的に向上させたい場合
• 設計書レビュー後、指摘事項の修正を自動化したい場合
• CI/CD パイプラインの一環としてドキュメント品質を担保したい場合
• 新規作成した設計書の品質チェックと自動修正を一気通貫で行いたい場合

品質基準（合格条件）

指標	合格条件
Critical 指摘数	0 件（1 件でもあれば不合格）
High 指摘数	0 件（1 件でもあれば不合格）
Medium / Low	件数は記録するが、合格判定には影響しない

安全制限

制限	値	理由
最大イテレーション回数	5 回	無限ループ防止
イテレーション間の確認	3 回目以降は修正前にユーザー確認を推奨	品質収束しない場合の早期検知
同一指摘の再発上限	同一 ID の指摘が 3 回連続で再発 → エスカレーション	自動修正不可能な根本課題の検出

---

前提条件

1. 対象ドキュメントが design-docs/ ディレクトリに存在すること
2. orchest-doc-review Agent（.github/agents/orchest-doc-review.agent.md）が利用可能であること
3. レビューレポート出力先 .github/review-reports/doc-review/ ディレクトリが存在すること
4. プロジェクトの規約ファイル（AGENTS.md、.github/instructions/*.instructions.md）にアクセス可能であること

---

手順

Phase 1: 初期化

1. 対象ドキュメントの確定

   • ユーザーから対象ドキュメント名を受け取る（例: spec, api-gateway-design, full）
   • design-docs/<対象名>.md の存在を確認する
   • full 指定の場合は design-docs/ 配下の全 .md ファイルを対象とする
   • 複数ファイル指定の場合: カンマ区切り（例: spec, authentication-service-design）または full で複数ファイルを受け付ける

2. イテレーションカウンターの初期化

   • iteration = 0
   • max_iterations = 5
   • 過去の修正履歴を追跡するための空リストを作成
   • 複数ファイルの場合: ファイルごとにイテレーション状態を管理する（ファイル A が合格しても、ファイル B が不合格なら B のみ再レビュー）

3. 既存レポートの確認

   • .github/review-reports/doc-review/<対象名>-check-report-*.md を検索
   • 既存レポートの最大番号を取得（次回のレポート番号決定用）

Phase 1.5: 修正前整合性チェック（14 Agent 実行前の低コスト検証）

目的: 14 Agent によるレビュー実行前に、過去の品質ゲートで繰り返し検出された機械的に検証可能な整合性問題を事前排除する。これにより「修正→新規問題→再修正」のモグラ叩きループを防止する。

3.5. 整合性チェックの実行

• 以下のチェックを対象ドキュメントに対して順番に実行する
• 不整合が検出された場合、Phase 2 に進む前に自動修正を適用する
• 全チェック通過後にのみ Phase 2（Agent レビュー）に進む

チェック項目一覧:

#	チェック名	検証内容	判定基準
1	snake_case 命名スキャン	SQL DDL 内のカラム名・テーブル名が全て snake_case であること	camelCase / PascalCase のカラム名を grep で検出
2	CHECK 制約網羅性	ステータス系カラム（status, type, role, state 等）に CHECK 制約が定義されていること	テーブル定義内のステータス系カラムと CHECK 制約を突合
3	CHECK 制約値の UPPER_CASE	CHECK 制約内の列挙値が全て UPPER_CASE であること	CHECK.*'[a-z] パターンで小文字値を検出
4	監査カラム存在	全テーブルに created_at / updated_at カラムが存在すること	テーブル定義を走査
5	FK カラムのインデックス	*_id カラム（FK 候補）に対応するインデックスが定義されていること	FK カラムとインデックス定義を突合
6	AppHost / Mermaid 三点照合	サービス一覧表、AppHost コード、Mermaid 図のサービス数と接続が一致すること	各セクションからサービス名を抽出し集合比較
7	Outbox ステータス値統一	Outbox 関連のステータス値が全箇所で同一表記であること	outbox を含むセクションのステータス値を収集し重複排除
8	コード例基本規約	コード例が primary constructor、CancellationToken ct = default、ILogger<T> メッセージテンプレートを使用していること	コードブロック内を走査

自動修正のルール:

• 上記チェックで検出された不整合は、14 Agent の指摘を待たずに即座に修正する
• 修正時は references/addition-checklist.md を参照し、修正の付随要素が漏れないことを確認する
• 修正内容は Phase 4 と同じ形式で fix-report に記録する

Phase 2: レビュー実行（ループ開始点）

4. イテレーションカウンターのインクリメント

   • iteration += 1
   • iteration > max_iterations の場合 → Phase 6（タイムアウト終了）へ

5. 現在日時の取得

   • date '+%Y-%m-%d %H:%M' コマンドで実際の現在日時を取得する（ハードコードしない）

6. orchest-doc-review Agent の呼び出し

   単一ファイルの場合（従来どおり）:

   • 対象ドキュメントを指定して orchest-doc-review Agent を実行する
   • Agent は内部で 14 サブエージェントを並列実行し、統合レポートを生成する
   • レポートは .github/review-reports/doc-review/<対象名>-check-report-<N>.md に保存される
   • <N> は通算レビュー回数（既存レポートの最大番号 + 1）

   複数ファイルの場合（並列実行）:

   • agent ツールの並列呼出し機能を使用して、未合格の各ファイルに対して orchest-doc-review Agent を同時に起動する
   • 各呼出しには対象ファイルを 1 つだけ指定し、Phase 1 で準備した共通コンテキスト（規約・技術スタック）を含める
   • 全 Agent の完了を待機し、ファイルごとのレポートを収集する
   • レポートはファイルごとに .github/review-reports/doc-review/<ファイル名>-check-report-<N>.md に保存される

   # 並列呼出し例（full モードで 3 ファイルが未合格の場合）:
   agent orchest-doc-review: "spec.md をレビューして"                 ─┐
   agent orchest-doc-review: "authentication-service-design.md を..."  ├─ 同時並列
   agent orchest-doc-review: "inventory-management-design.md を..."    ─┘
   # → 各 Agent 内部でさらに 14 サブエージェントが並列実行される
   

   合格済みファイルのスキップ: 複数ファイルの品質ゲートループでは、前回イテレーションで合格（Critical == 0 AND High == 0）したファイルは再レビューをスキップする。未合格ファイルのみ再レビューを実行する。

7. レポート解析

   • 生成されたレポートを読み込む
   • 以下の情報を抽出する:
     • Critical 指摘の件数と一覧
     • High 指摘の件数と一覧
     • Medium / Low 指摘の件数（参考情報として記録）
     • 各指摘の ID、出典 Agent、カテゴリ、対象箇所、指摘内容、推奨対応

Phase 3: 合格判定

8. 品質基準の評価

   • 単一ファイル: Critical == 0 AND High == 0 → 合格 → Phase 5（成功終了）へ。それ以外 → 不合格 → Phase 4（自動修正）へ
   • 複数ファイル: ファイルごとに合否を判定する
     • 全ファイルが合格 → Phase 5（成功終了）へ
     • 1 つ以上のファイルが不合格 → 不合格ファイルのみ Phase 4（自動修正）→ Phase 2 再レビューへ（合格済みファイルはスキップ）

9. 進捗の確認（イテレーション 3 回目以降）

   • 前回イテレーションと比較して Critical/High が減少しているか確認
   • 減少していない場合、以下を出力してユーザーに確認を求める:

     ⚠️ イテレーション {N} でも Critical/High が減少していません。
     残存: Critical={X}, High={Y}
     対象ファイル: {ファイル名}（複数ファイル時）
     続行しますか？ [続行 / 中断してレポート出力]
     

   • 同一指摘 ID が 3 回連続で再発している場合:

     ⚠️ 以下の指摘が 3 回連続で解消されていません（自動修正困難と判断）:
     - {指摘ID}: {指摘内容}（対象: {ファイル名}）
     人間によるレビューを推奨します。
     

Phase 4: 自動修正（ドキュメント直接編集）

重要: このフェーズでは対象ドキュメント（design-docs/<対象名>.md）を edit ツールで直接編集 する。 レポートを参照するだけでなく、実際にファイルの内容を書き換える ことで品質を向上させる。

Step 10: 修正優先順位の決定

修正パターンガイド に基づき、以下の優先順で修正する:

1. 🔴 Critical（全件）: アーキテクチャ根幹、セキュリティ、法規制
2. 🟡 High — アーキテクチャ系: サービス境界、DDD、通信パターン
3. 🟡 High — セキュリティ/GDPR系: 認証認可、暗号化、データ保護
4. 🟡 High — DB/データ系: スキーマ設計、制約、インデックス
5. 🟡 High — ビジネス要件系: 要件定義、状態遷移、計算ルール
6. 🟡 High — その他: テスト、CI/CD、インフラ、アクセシビリティ

Step 11: 規約ファイルの事前読み込み

修正の品質を担保するため、修正作業の前に以下の規約ファイルを読み込み、修正内容が規約に準拠していることを保証する:

1. AGENTS.md — プロジェクト全体の規約（最上位）
2. .github/instructions/dotnet-coding-standards.instructions.md — コーディング規約
3. .github/instructions/security-coding.instructions.md — セキュリティ規約
4. .github/instructions/api-design.instructions.md — API 設計規約
5. その他、指摘カテゴリに関連する instructions ファイル

Step 12: 指摘ごとの修正実行（1 件ずつ順番に処理）

各 Critical/High 指摘に対して、以下の 5 ステップ を実行する:

12a. 指摘内容の解析

レビューレポートから以下を抽出する:

• 指摘 ID（例: C1, H15）
• 出典 Agent（例: architect, security-reviewer）
• カテゴリ（例: サービス境界、GDPR）
• 指摘内容（何が問題か）
• 推奨対応（どう修正すべきか）
• 対象箇所（レポートに記載されている場合）

12b. 対象ドキュメント内の該当箇所を特定

以下のツールを使って修正すべき箇所を正確に特定する:

# 1. grep で指摘に関連するキーワードを検索し、行番号を特定する
grep -n "キーワード" design-docs/<対象名>.md

# 2. view ツールで該当箇所の前後コンテキスト（±20行程度）を確認する
view design-docs/<対象名>.md [開始行, 終了行]

# 3. 修正対象の正確なテキスト範囲を確定する

重要: 修正前に必ず view で該当箇所を確認し、old_str に使う正確なテキストを把握すること。

12b-2. 影響範囲スキャン（修正前の関連セクション特定）

目的: 修正が他セクションに波及する影響を修正実行前に特定し、同時修正計画を立てる。これにより「修正→新規問題→再修正」のモグラ叩きループを防止する。

以下の手順で影響範囲を網羅的に特定し、全関連箇所を同時に修正する:

Step A — キーワード抽出: 修正対象から以下のキーワードを抽出する

• エンティティ名 / テーブル名（例: Order, orders）
• サービス名（例: SalesManagementService）
• Kafka トピック名（例: order.created）
• ステータス値（例: PENDING, COMPLETED）
• 設計パターン名（例: Saga, Outbox）

Step B — grep 一括検索: 抽出したキーワードで全出現箇所を検索する

# 1. 修正対象のキーワードで全出現箇所を検索
grep -n "キーワード1\|キーワード2\|キーワード3" design-docs/<対象名>.md

# 2. 結果をセクション単位で整理し、修正が必要な関連箇所を列挙する

Step C — 影響マトリクスで関連セクションを特定: 修正内容の種別に応じて、以下のマトリクスで関連セクションを自動判定する

修正内容の種別	必ず確認すべき関連セクション
テーブル / エンティティ変更	① エンティティ定義テーブル ② CHECK制約セクション ③ インデックス設計 ④ 監査カラム ⑤ C#エンティティクラス例 ⑥ AppDbContext定義
Kafka トピック変更	① トピック一覧テーブル ② 発行/購読サービスの記載 ③ AppHost コード ④ Mermaid 構成図（ローカル・Azure 両方）
サービス間通信変更	① Saga ステップ定義 ② AppHost WithReference ③ Mermaid 構成図 ④ gRPC proto 定義 ⑤ タイムアウト/Deadline
ステータス値の追加/変更	① 状態遷移図 ② CHECK 制約定義 ③ 全文中の同一ステータス値（表記統一）
GDPR / PII 変更	① RoPA テーブル ② データ保持ポリシー ③ DSR フロー ④ 暗号化対象一覧 ⑤ DPIA セクション
コード例の変更	① 同一クラスの他コード例 ② primary constructor パラメータ整合性 ③ 関連 DI 登録例
Mermaid 図の変更	① 対応する Mermaid 図（ローカル↔Azure の同期） ② サービス一覧テーブル ③ AppHost コード

Step D — 同時修正計画の策定: 影響範囲スキャンの結果に基づき、修正計画を以下の形式で整理してから edit を実行する

📋 修正計画（指摘 {ID}）:
  - 主修正: {セクション名}（L{行番号}）— {修正内容}
  - 関連修正 1: {セクション名}（L{行番号}）— {連動修正内容}
  - 関連修正 2: {セクション名}（L{行番号}）— {連動修正内容}
  - 確認済み影響なし: {セクション名} — {影響がない理由}

ルール:

• 主修正と関連修正は同一指摘の処理として一括で実行する（次の指摘に進む前に全関連修正を完了する）
• 関連セクションが修正不要と判断した場合も、「確認済み影響なし」として記録する（スキャン漏れ防止）
• 新規追加チェックリスト の該当セクションも参照し、付随要素の漏れを確認する

12c. edit ツールでドキュメントを直接編集する

修正パターン A — 既存テキストの修正:

edit ツールを使用:
  path: design-docs/<対象名>.md
  old_str: <修正前のテキスト（view で確認した正確な内容）>
  new_str: <修正後のテキスト（指摘の推奨対応に基づく改善内容）>

修正パターン B — 新規セクションの追加:

edit ツールを使用:
  path: design-docs/<対象名>.md
  old_str: <挿入位置の直前にある既存テキスト>
  new_str: <既存テキスト>

<追加する新規セクションの全文>

修正パターン C — テーブルへの行追加:

edit ツールを使用:
  path: design-docs/<対象名>.md
  old_str: | 既存の最終行 | ... |
  new_str: | 既存の最終行 | ... |
| 追加行 | ... |

修正の原則:

• old_str はドキュメント内で 一意に特定できる 十分な長さにする
• 既存の正しい記述を不必要に削除しない（追記・修正が基本）
• Mermaid 図を修正する場合、構文の正しさを確認する
• コードブロック内の修正では、インデントと構文を正確に維持する
• 1 つの指摘に対して複数箇所の修正が必要な場合、edit を複数回呼び出す

12d. 修正後の検証

各修正の適用後、以下を確認する:

# 1. 修正箇所を view で確認し、意図した変更が正しく反映されているか検証する
view design-docs/<対象名>.md [修正行の前後]

# 2. 修正が他のセクションと矛盾していないか、関連キーワードで grep する
grep -n "関連キーワード" design-docs/<対象名>.md

# 3. Mermaid 図の場合、開始/終了タグが正しく対応しているか確認する
grep -n "```mermaid\|```$" design-docs/<対象名>.md

検証で問題が見つかった場合: 即座に edit で修正する（不整合を残したまま次の指摘に進まない）

12e. 修正記録の蓄積

修正した内容を内部リストに追加する（修正ログ作成用）:

• 指摘 ID
• 修正の概要（何を変更したか、1〜2 文で）
• 修正箇所（セクション名 + おおよその行範囲）
• 修正パターン（A: 既存修正 / B: 新規追加 / C: テーブル行追加）

Step 13: 全指摘の修正完了後の整合性チェック

全 Critical/High 指摘の修正が完了したら、ドキュメント全体の整合性を確認する:

1. セクション間の参照整合性: 修正で追加/変更したセクションが他セクションから正しく参照されているか
2. Mermaid 図の構文チェック: 追加/変更した図が構文エラーを含んでいないか
3. 用語の一貫性: 修正で新たに導入した用語が既存の用語と矛盾していないか
4. テーブルの罫線崩れ: Markdown テーブルのカラム数が見出しと一致しているか

問題が見つかった場合は edit で修正する。

Step 14: 修正ログの保存

.github/review-reports/doc-review/<対象名>-fix-report-<N>.md に修正内容を記録する。 <N> は対応するチェックレポートと同じ番号。 修正ログは create ツールで新規ファイルとして作成する:

# ドキュメント修正ログ

- **対象**: design-docs/<対象名>.md
- **イテレーション**: <N> / <max_iterations>
- **修正日時**: （date コマンドで取得した実際の現在日時）
- **対応レビュー**: <対象名>-check-report-<N>.md

## 修正サマリー
| 修正件数 | Critical | High | 合計 |
|---------|----------|------|------|
| 修正済み | X | Y | Z |
| 修正不可（エスカレーション） | A | B | C |

## 修正詳細
| # | 指摘ID | 重要度 | 出典Agent | 修正パターン | 修正箇所（セクション） | 修正内容の概要 |
|---|--------|--------|----------|-------------|---------------------|-------------|
| 1 | C1 | Critical | architect | B: 新規追加 | §X.Y に新規セクション追加 | ... |
| 2 | H3 | High | performance | A: 既存修正 | §X.Y のテーブルを更新 | ... |

## 修正不可事項（人間対応が必要）
| # | 指摘ID | 重要度 | 理由 | 推奨対応者 |
|---|--------|--------|------|-----------|

Step 15: Phase 2 へ戻る（ループ）

修正ログの保存が完了したら、Phase 2（レビュー実行）に戻り、修正後のドキュメントを再レビューする。

Phase 5: 成功終了

14. 品質ゲート通過レポートの生成

    • .github/review-reports/doc-review/<対象名>-quality-gate-passed.md に最終レポートを保存する
    • レポートには以下を含める:
      • 最終判定: ✅ PASSED
      • 実施日時（date コマンドで取得した実際の現在日時）
      • 総イテレーション回数
      • イテレーションごとの Critical/High 推移
      • 修正の全履歴（各イテレーションで何を修正したか）
      • 残存する Medium/Low 指摘の件数

15. 完了メッセージの出力

    ✅ ドキュメント品質ゲート通過
    対象: <対象ドキュメント>
    イテレーション: <N> 回で合格
    修正件数: Critical <X>件 + High <Y>件 = 合計 <Z>件
    

Phase 6: タイムアウト終了（最大イテレーション超過）

16. タイムアウトレポートの生成

    • .github/review-reports/doc-review/<対象名>-quality-gate-timeout.md に最終レポートを保存する
    • レポートには以下を含める:
      • 最終判定: ❌ NOT PASSED（タイムアウト）
      • 実施日時
      • 総イテレーション回数（= max_iterations）
      • イテレーションごとの Critical/High 推移（減少傾向の確認）
      • 残存する Critical/High 指摘の一覧
      • 自動修正で解消できなかった指摘の分析
      • 人間による対応が必要な項目のリスト

17. エスカレーションメッセージの出力

    ❌ ドキュメント品質ゲート未通過（最大 <max_iterations> 回に到達）
    残存: Critical=<X>, High=<Y>
    以下の指摘は自動修正困難です。人間によるレビューを推奨します:
    - <指摘一覧>
    

---

出力フォーマット

品質ゲート通過レポート

# ドキュメント品質ゲート結果

## 判定
- **対象**: <対象ドキュメント>
- **判定**: ✅ PASSED / ❌ NOT PASSED（タイムアウト）
- **実施日時**: （date コマンドで取得した実際の現在日時）
- **総イテレーション回数**: <N> / <max_iterations>

## イテレーション推移

| イテレーション | Critical | High | Medium | Low | 判定 |
|--------------|----------|------|--------|-----|------|
| 1 | X | Y | ... | ... | ❌ |
| 2 | X' | Y' | ... | ... | ❌ |
| ... | ... | ... | ... | ... | ... |
| N | 0 | 0 | ... | ... | ✅ |

## 修正履歴

### イテレーション 1
- レビューレポート: <対象名>-check-report-<N>.md
- 修正ログ: <対象名>-fix-report-<N>.md
- 修正件数: Critical <X> + High <Y>
- 主な修正内容:
  - ...

### イテレーション 2
...

## 残存指摘（Medium / Low）
| # | 重要度 | カテゴリ | 指摘内容 |
|---|--------|---------|---------|

---

レポート永続化ルール

1. チェックレポート: .github/review-reports/doc-review/<対象名>-check-report-<N>.md

   • orchest-doc-review Agent が生成する標準レビューレポート
   • <N> はインクリメンタル番号（既存の最大番号 + 1）

2. 修正ログ: .github/review-reports/doc-review/<対象名>-fix-report-<N>.md

   • 各イテレーションで適用した修正の詳細記録
   • 対応するチェックレポートと同じ番号 <N> を使用する

3. 品質ゲート結果: .github/review-reports/doc-review/<対象名>-quality-gate-passed.md または <対象名>-quality-gate-timeout.md

   • 品質ゲート全体の最終レポート（イテレーション推移、修正履歴を含む）

4. 削除禁止: 過去のレポートは修正・削除しない（監査証跡）

5. 日時の記録: 全レポート内の日時は date '+%Y-%m-%d %H:%M' コマンドで実際の現在日時を取得して記入する

---

参照ドキュメント

• 修正パターンガイド — 指摘カテゴリ別の修正方法
• orchest-doc-review Agent（.github/agents/orchest-doc-review.agent.md） — レビュー実行エンジン