CAPHTECH Review Report Generator
レビュー結果を意思決定に耐える形式のレポートに整形する。
核心: 網羅的な指摘より「意思決定に必要な形」を優先する。
前提条件
必須:
architecture-review/*/review.yaml- architecture-reviewer の統合出力（findings + conflicts + prioritized_actions）
推奨:
system-map/invariants.yaml- 不変条件
出力形式の選択
$ARGUMENTS で出力形式を決定する。未指定の場合は chat をデフォルトにする。
| 値 | 動作 | 用途 |
|---|---|---|
chat |
チャットで直接報告 | 素早い確認、口頭報告の下書き |
file |
ファイル群を生成 | チーム共有、ドキュメント保存 |
issue |
GitHub Issueを作成 | バックログ追加、タスク管理 |
判定ロジック:
$ARGUMENTSがfileなら file 形式で出力する$ARGUMENTSがissueなら issue 形式で出力する- それ以外（空・
chat・不明な値）は chat 形式で出力する
形式1: chat（チャット報告）
チャットにMarkdownで直接報告する。ファイルは生成しない。
出力構成
- エグゼクティブサマリー - 優先度別の件数テーブル
- P0/P1 詳細 - 各指摘の問題・推奨案・PR分割・受け入れ条件
- P2以下サマリー - 件数と主要項目のタイトルのみ
出力例（サマリー部分）
# アーキテクチャレビュー報告書
**レビュー日**: 2024-01-21
**対象**: order-service, payment-service, inventory-service
## サマリー
| カテゴリ | 件数 | 対応状況 |
|---------|------|---------|
| P0 (Blocker) | 2 | 即時対応必須 |
| P1 (Critical) | 3 | 今スプリント |
| P2 (High) | 5 | 次スプリント |
| P3/P4 | 8 | バックログ |
P0/P1の各指摘には以下を含める:
- 問題の概要と影響
- 対応案のテーブル（案・内容・工数・推奨マーク）
- PR分割（タイトル・スコープ・サイズ）
- 受け入れ条件（チェックリスト形式）
- ADR要否
形式2: file（ファイル出力）
architecture-review/{timestamp}/report/ 配下にファイル群を生成する。
ファイル構造
architecture-review/{timestamp}/
├── review.yaml # architecture-reviewer の統合出力（既存）
└── report/ # 本スキルの出力
├── summary.md # エグゼクティブサマリー
├── p0-blockers.md # P0詳細（全フィールド）
├── p1-critical.md # P1詳細（全フィールド）
├── p2-high.md # P2詳細
├── backlog.md # P3/P4
└── adrs-needed.md # 必要なADR一覧
各ファイルの内容
| ファイル | 内容 |
|---|---|
| summary.md | 件数テーブル + P0/P1の1行サマリー + 推奨アクション |
| p0-blockers.md | P0の全指摘。問題・根拠・対応案・PR分割・受け入れ条件 |
| p1-critical.md | P1の全指摘。p0-blockers.md と同形式 |
| p2-high.md | P2の全指摘。対応案は推奨のみ記載 |
| backlog.md | P3/P4。タイトル・スコープ・推奨案・工数の一覧表 |
| adrs-needed.md | ADRが必要な指摘のリスト。トピック・関連指摘・背景 |
用途別の推奨ファイル
| 用途 | 使うファイル |
|---|---|
| ステークホルダー報告 | summary.md のみ |
| 開発チーム共有 | 全ファイル |
| PR作成 | p0-blockers.md + PR分割情報 |
| バックログ追加 | backlog.md をIssue化 |
形式3: issue（GitHub Issue作成）
gh issue create で指摘をGitHub Issueとして作成する。
作成ルール
| 優先度 | Issue数 | ラベル |
|---|---|---|
| P0 | 指摘ごとに1つ | architecture-review, P0-blocker |
| P1 | 指摘ごとに1つ | architecture-review, P1-critical |
| P2以下 | まとめて1つ | architecture-review |
P0/P1 個別Issueの内容
各Issueに以下を含める:
- タイトル:
[{priority}] {title} - 概要と影響範囲
- 発生条件
- 根拠（evidence）
- 対応案テーブル + 推奨
- PR分割
- 受け入れ条件（チェックリスト形式）
- ADR要否
詳細なテンプレートは references/issue-template.md を参照。Issue本文のフォーマットとghコマンド例が記載されている。
P2以下まとめIssue
1つのIssueに全P2以下の指摘をまとめる:
- タイトル:
[Architecture Review] P2以下の指摘事項まとめ（{件数}件） - P2は各指摘の概要・推奨案・工数を記載
- P3/P4はタイトルとスコープのみ
実行手順
- review.yaml から全指摘を読み込む
- 指摘を優先度でグルーピングする
- P0の指摘から順に
gh issue createを実行する - P1の指摘を同様に実行する
- P2以下をまとめて1つのIssueを作成する
- 作成したIssueのURL一覧をチャットに報告する
指摘の標準形式
各指摘は以下のフィールドを持つ。詳細なYAML例は references/finding-format.md を参照。各フィールドの選択基準や算出方法が記載されている。
| フィールド | 必須 | 内容 |
|---|---|---|
| id | Yes | FINDING-001 形式の一意ID |
| title | Yes | 問題の端的な名称 |
| scope.type | Yes | component / interaction / crosscutting |
| scope.affected | Yes | 影響を受けるコンポーネント |
| failure_mode.description | Yes | 何が成立しなくなるか |
| failure_mode.impact | Yes | ユーザー・ビジネス・システムへの影響 |
| trigger_conditions | Yes | 発生条件のリスト |
| evidence | Yes | 根拠（source, field, value） |
| options | Yes | 対応案のリスト（id, action, pros, cons, effort） |
| priority.category | Yes | P0 / P1 / P2 / P3 / P4 |
| priority.score | Yes | severity x likelihood x detectability x quality_weight |
| priority.rationale | Yes | 優先度判断の理由 |
| implementation.recommended_option | Yes | 推奨する対応案のID |
| implementation.pr_breakdown | Yes | PR分割（タイトル, スコープ, サイズ） |
| implementation.adr_needed | Yes | ADR作成要否 |
| acceptance_criteria.tests | Yes | テスト条件 |
| acceptance_criteria.metrics | No | 定量メトリクス |
| acceptance_criteria.logs | No | ログ確認項目 |
| acceptance_criteria.contract | No | API契約の変更 |
注意事項
- 推測禁止: evidence がない指摘はレポートに含めない
- 実行可能な形式: 「問題がある」だけでなく「何をするか」まで書く
- PR単位まで分割: 「改善する」ではなく「このPRを作る」と具体化する
- 受け入れ条件の明示: 完了判定ができる形で記載する
- issue形式でのラベル: 事前に
architecture-review,P0-blocker,P1-criticalラベルが存在しない場合はgh label createで作成する