issue-review

イシューのレビュー

エキスパートのペルソナを用いて、GitLab または GitHub のイシューを複数の視点から完全自律でレビューします。このスキルは、イシューのコンテキストを取得し、関連するコードベースを調査し、3 ラウンドのペルソナ会議（冒頭の見解、討論、重み付けによる意見の収束）を実施したうえで、確認を求めることなく、構造化されたレビューコメントをイシューに直接投稿します。

前提条件

• gh（GitHub CLI）：プロジェクトが GitHub を使用している場合に必要です。https://cli.github.com または brew install gh からインストールしてください
• glab（GitLab CLI）：プロジェクトが GitLab を使用している場合に必要です。https://gitlab.com/gitlab-org/cli または brew install glab からインストールしてください

このスキルを使うタイミング

ユーザーが次の操作をしたときに有効化します。

• イシューについて「イシューのレビュー」または「issue review」を依頼する
• 「issue-review #42」または「issue-review 」と指示する
• 実装前に、イシューを複数の視点から分析したいと希望する
• イシューの実現可能性、完全性、リスクについて、構造化された意見を求める

基本原則

1. 完全な自律性

• （クローズ済みのイシューを除き、「例外的なケース」を参照）ユーザーに質問することなく、パイプライン全体を実行します
• イシューの内容分析に基づいて、ペルソナを自動的に選択します
• レビューコメントをイシューに直接投稿します

2. 複数の視点からの分析

• ペルソナが実現可能性、完全性、リスク、アーキテクチャをレビューします
• 3 回の完全なラウンドを通して、実質的な議論を行い、より深い分析を実現します
• 各ペルソナはそれぞれ異なる視点を提供します

3. コンテキストを踏まえた深い分析

• イシューの全情報（説明、すべてのコメント、ラベル）を読み込みます
• ブランチが関連付けられている場合は、そのブランチの差分を分析します
• 既存のコードベースを自動的に調査し、ペルソナに的確なコンテキストを提供します

4. 分析のみ

• このスキルは何も実装しません
• 実行可能な次のステップを含むレビューを作成します
• チームは分析を読み、対応を決定します

ワークフロー

Step 1: イシューの特定と取得

1. ユーザーの入力を解析して、イシューの参照情報を抽出します。

   • イシュー番号：#42
   • 完全な URL：https://gitlab.example.com/group/project/-/issues/42 または https://github.com/owner/repo/issues/42
   • 有効なイシュー参照が見つからない場合は、ユーザーに提示を求めます

2. リモートリポジトリの種類を判定します。

   • git remote -v を実行して、リモートが GitLab か GitHub かを判定します
   • 手順 7（コメントの投稿）で使うために、この情報を保存します

3. イシューの詳細を取得します。

   • GitLab： glab issue view <iid> — タイトル、説明、ラベル、状態
   • GitHub： gh issue view <number> — タイトル、本文、ラベル、状態

4. イシューのコメントをすべて取得します。

   • GitLab： glab issue note list <iid> または glab api /projects/:id/issues/:iid/notes
   • GitHub： gh issue view <number> --comments

5. イシューの状態を確認します。

   • イシューがクローズ済みの場合は、ユーザーに警告し、続行する前に確認を求めます（「例外的なケース」を参照）
   • イシューがオープンの場合は、通常どおり続行します

6. 内容が最低限そろっているか確認します（「例外的なケース」を参照）。

   • イシューに説明がない場合、または意味のある内容がなくタイトルが 1 行だけの場合は、会議を省略し、不足している項目を列挙した短いコメントを投稿します

Step 2: コンテキストをすべて収集

イシューのコンテキスト

• イシューのタイトル、説明、すべてのコメント（手順 1 で収集済み）
• ラベルとマイルストーン（ドメインの判定に使用）

関連ブランチのコンテキスト

1. 関連ブランチを確認します。
   • GitLab： glab api /projects/:id/issues/:iid/related_merge_requests を使って、関連するマージリクエストを確認するか、イシューやコメント内のブランチ参照を探します
   • GitHub： gh pr list --search "<issue reference>" を使って、関連するプルリクエストを確認します
2. ブランチが存在する場合：
   • 差分を取得します：git diff main...<branch>（または適切なベースブランチ）
   • 差分の概要と主なファイル変更をペルソナのコンテキストに含めます

コードベースのコンテキスト

1. 課題の内容を分析し、コードベースのどの部分が関連するかを特定します。
   • 課題やコメントで言及されているファイルパス、モジュール名、関数名、コンポーネント
   • 特定のディレクトリやファイルに対応するドメインキーワード
2. コードベースを調査します。関連ファイルを読み、現状を把握します。
   • Glob と Grep を使用して関連ファイルを探します
   • 最も関連性の高いファイルを読みます（明示的に言及されているファイルを優先し、次に関連モジュールのファイルを確認します）
   • 既存のパターン、アーキテクチャ、規約を把握します
3. ペルソナ向けに、次の内容を含むコンテキストの要約を作成します。
   • 課題の内容（説明とコメント）
   • リンクされたブランチの差分（ある場合）
   • 関連するコードベースの抜粋とアーキテクチャの概要

ステップ 3：ペルソナを自動選択する

課題の内容、ラベル、ドメインに基づいて、3～4 人のペルソナを自動的に選択します。次の基準を使用します。

対象となるテーマ...	自動選択されるペルソナ
バックエンド／API／データベース	SOLID Alex（バックエンド）、Whiteboard Damien（アーキテクト）、EXPLAIN PLAN Isabelle（Oracle DBA）
フロントエンド／UI／UX	Pixel-Perfect Hugo（フロントエンド）、Figma Fiona（UX/UI）、Sprint Zero Sarah（PO）、Whiteboard Damien（アーキテクト）
セキュリティ／認証／アクセス制御	Paranoid Shug（セキュリティ）、RGPD Raphaël（DPO）、SOLID Alex（バックエンド）、Whiteboard Damien（アーキテクト）
インフラストラクチャ／デプロイ／CI-CD	Pipeline Mo（DevOps）、SOLID Alex（バックエンド）、Whiteboard Damien（アーキテクト）
データ／移行／ETL	Schema JB（データ）、EXPLAIN PLAN Isabelle（Oracle DBA）、Whiteboard Damien（アーキテクト）
相互運用性／HL7／FHIR／HPK	RFC Santiago（相互運用性 PO）、HL7 Victor（相互運用性開発）、SOLID Alex（バックエンド）
レガシー／Uniface／モダナイゼーション	Legacy Larry（Uniface）、Whiteboard Damien（アーキテクト）、SOLID Alex（バックエンド）
テスト／品質／リグレッション	Edge-Case Nico（QA）、SOLID Alex（バックエンド）、Pipeline Mo（DevOps）
プロダクト／機能／UX の判断	Sprint Zero Sarah（PO）、Pixel-Perfect Hugo（フロントエンド）、Figma Fiona（UX/UI）、Whiteboard Damien（アーキテクト）
医療／臨床ワークフロー	Dr. Workflow Wendy（医療）、Sprint Zero Sarah（PO）、RGPD Raphaël（DPO）
RGPD／個人データ／コンプライアンス	RGPD Raphaël（DPO）、Paranoid Shug（セキュリティ）、Whiteboard Damien（アーキテクト）
BI／ダッシュボード／レポート／財務／会計	Dashboard Estelle（財務 BI）、Pixel-Perfect Hugo（フロントエンド）、EXPLAIN PLAN Isabelle（Oracle DBA）、Whiteboard Damien（アーキテクト）
フルスタック／横断的なテーマ	Whiteboard Damien（アーキテクト）、SOLID Alex（バックエンド）、Sprint Zero Sarah（PO）、Edge-Case Nico（QA）

複数のドメインにまたがる場合は、最も関連性の高い 3～4 人のペルソナを選択します。

役割、視点、バイアスを含むペルソナの全一覧： reference/personas.md を参照してください。

ミーティングを始める前に、選択したペルソナとその役割を発表してください。

ステップ 4：レビュー会議を実施する

会議ではサブエージェントを使い、各ペルソナが独立して並行に検討します。レビュー会議は、十分に検討するため、全 3 ラウンドで実施します。

重要：Agent ツールを使用して、各ペルソナを個別のサブエージェントとして起動してください。

ラウンド 1：冒頭意見（並列サブエージェント）

Agent ツールを使用し、ペルソナごとに 1 つのサブエージェントを並列で起動します。各サブエージェントには次の情報を渡します。

1. 課題のタイトルと説明
2. 収集したすべてのコンテキスト（コメント、ブランチの差分、コードベースの抜粋）
3. ペルソナのアイデンティティプロンプト

サブエージェントのプロンプトテンプレート：

You are {name}, a {role}.

Your perspective: {perspective}
Your natural bias: {bias}

You are reviewing an issue before implementation. Here is the issue:

**Title:** {issue_title}
**Description:** {issue_description}
**Comments:** {issue_comments}

Codebase context:
{codebase_context}

{branch_diff_context_if_any}

As {name}, provide your review:
1. **Feasibility:** Is this issue feasible as described? What's missing or unclear?
2. **Risks:** What are the top 2-3 risks? Be specific about failure scenarios from your domain.
3. **Completeness:** Are acceptance criteria clear enough to implement? What questions would you ask the PO?
4. **Architecture/Design:** How should this be approached technically? What patterns or constraints apply?
5. **Pushback:** What would you challenge from other typical perspectives?

Stay fully in character. Be concise and actionable. Use concrete examples, not abstract platitudes.

This is a research task — do NOT write or edit any files.

すべてのペルソナのサブエージェントを、1 つのメッセージ内で起動し、並列に実行してください。 subagent_type: "general-purpose" を使用し、"Review persona: {name}" のような短い説明を指定します。

すべての意見を集め、引用として提示します。

SOLID Alex（シニアバックエンドエンジニア）：「私はこう考えます……」

集団思考のチェック

Round 1 の回答を収集したら、合意の度合いを評価します。

1. すべてのペルソナが同じ評価に収束したかを確認します（同じ判定で、意味のある意見の相違がない）
2. 合意の度合いが高すぎる場合（すべてのペルソナが反論なく同意している場合）：
   • 悪魔の代弁者として、追加のサブエージェントを1つ起動します。

     あなたは、ある課題を検討する悪魔の代弁者です。
     
     すべてのレビュアーが、次の評価に同意しました：{consensus_summary}
     
     あなたの仕事は、この合意に反対する最も強力な論拠を見つけることです。
     - 誰も言及しなかったリスクは何ですか？
     - 全員が前提としているものの、誤っている可能性があるものは何ですか？
     - すぐに退けられたエッジケースや障害モードは何ですか？
     
     具体的かつ明確に述べてください。実際に起こりうる障害シナリオを挙げてください。
     これは調査タスクです。ファイルの作成や編集はしないでください。
     

   • 反対意見を分析に含めます。
3. **すでに意味のある意見の相違がある場合：**そのまま Round 2 に進みます。

Round 2：議論と異議（並列サブエージェント）

2回目の並列サブエージェント群（ペルソナごとに1つ）を起動します。各サブエージェントには、次の内容を渡します。

1. 課題の詳細
2. Round 1 のすべての冒頭意見（全ペルソナ分）
3. そのペルソナのアイデンティティプロンプト

Round 2 のサブエージェントプロンプトのテンプレート：

You are {name}, a {role}.

Your perspective: {perspective}
Your natural bias: {bias}

You are in a review meeting about this issue:

**Title:** {issue_title}

Here are the opening statements from all reviewers:
{all_opening_statements}

As {name}, react to the other reviewers' positions:
1. Which assessments do you agree with and why?
2. Which assessments do you challenge? Be specific about what's wrong or missing.
3. What risks or gaps have the others missed?
4. Have any of the other statements changed your assessment? If so, how?
5. State your updated verdict: is this issue ready for implementation, needs adjustments, or needs a rethink?

Be direct and create genuine debate. Challenge assumptions. Reference specific points from the other statements. It's OK to disagree strongly. It's also OK to change your mind if convinced.

This is a research task — do NOT write or edit any files.

Round 2 では、すべてのペルソナのサブエージェントを1つのメッセージで起動してください。

**このラウンドでは、実質的な緊張関係を生み出す必要があります。**サブエージェントが全員同意した場合は、1つのエージェントに多数派の立場への悪魔の代弁者を務めるよう追加でプロンプトを送ります。

Round 3：重み付けによる収束

Round 2 の回答をすべて収集した後、あなた（サブエージェントではなく、進行役）が議論をまとめます。

1. 専門分野との関連性に応じて立場に重みを付けます。

   • 各ペルソナについて、その課題が専門知識にどれほど密接に関連するかを評価します。
   • データベース移行の課題では、EXPLAIN PLAN Isabelle の立場は Pixel-Perfect Hugo よりも重く扱います。
   • UI 再設計の課題では、Pixel-Perfect Hugo の立場は EXPLAIN PLAN Isabelle よりも重く扱います。

2. 合意点と意見の相違を特定します。

   • すべてのペルソナが合意した点
   • 解消されていない意見の相違 — 明示的に列挙します。
   • 議論から浮かび上がった主なリスクと不足点

3. 課題の準備状況を評価します。

   • **実装の準備が整っている：**明確に定義され、実現可能で、リスクを管理できます。
   • **調整が必要：**実現可能ですが、詳細が不足している、受け入れ基準が不明確、またはリスクの緩和が必要です。
   • **大幅な手直しが必要：**重大な不足がある、スコープが不明確、またはアーキテクチャ上の懸念が未解決です。

4. 実行可能な次のステップをまとめます — チームが対応できる具体的なチェックリスト項目を作成します。

ステップ5：レビュー分析の作成

ユーザーに表示する、構造化された分析を作成します。

## Revue d'issue par personas IA

**Issue :** #XX — [titre de l'issue]

**Participants :** [Name (Role)] | [Name (Role)] | [Name (Role)]

### Contexte
[Résumé métier de l'issue — ce que l'utilisateur/patient/équipe gagne]

### Synthèse de la revue

#### Faisabilité
[Assessment: faisable en l'état / faisable avec réserves / nécessite clarification]

#### Complétude
[Are acceptance criteria clear? What's missing from the spec?]

#### Risques identifiés
- [Risque 1 en impact métier → Mitigation]
- [Risque 2 en impact métier → Mitigation]

#### Points techniques à considérer
[Only when personas surfaced architecture/security/performance concerns — omit section if none]

### Prochaines étapes recommandées
- [ ] [Action 1 — e.g., "Préciser les critères d'acceptation pour le cas X"]
- [ ] [Action 2 — e.g., "Valider l'impact sur le module Y avec l'équipe"]
- [ ] [Action 3]

### Verdict
[One of: ✅ Prête pour implémentation / ⚠️ Nécessite des ajustements avant implémentation / ❌ Nécessite une refonte significative]

ステップ6：Issue への投稿

レビュー分析を Issue のコメントとして投稿します。コメントはフッターを除き、ステップ5と同じ構成にします。

コメントのテンプレート（フランス語 — PO／コンサルタント向け、技術的な懸念を含む）

## Revue d'issue par personas IA

### Contexte
[Résumé métier de l'issue — ce que l'utilisateur/patient/équipe gagne]

### Participants
| Expert | Rôle | Verdict |
|--------|------|---------|
| [Name] | [Role] | [Position résumée en 1 ligne orientée impact métier] |
| ... | ... | ... |

### Synthèse de la revue

#### Faisabilité
[Assessment formulé en termes d'impact métier et de faisabilité technique]

#### Complétude
[Analyse de la complétude des critères d'acceptation et des cas d'usage décrits]

#### Risques identifiés
- [Risque 1 en impact métier → Mitigation proposée]
- [Risque 2 en impact métier → Mitigation proposée]

#### Points techniques à considérer
[Uniquement si des préoccupations architecture/sécurité/performance ont émergé — omettre cette section si aucun point technique notable]

### Prochaines étapes recommandées
- [ ] [Action 1]
- [ ] [Action 2]
- [ ] [Action 3]

### Verdict
[✅ Prête pour implémentation / ⚠️ Nécessite des ajustements avant implémentation / ❌ Nécessite une refonte significative]

---
_Revue générée automatiquement par IA_

適切なツールを使用してコメントを投稿します。

• GitLab： glab issue note <iid> --message "<comment>"
• GitHub： gh issue comment <number> --body "<comment>"

投稿に失敗した場合（API エラー、権限拒否）：

• 何も失われないよう、レビューコメント全文を会話に出力します。
• ユーザーがコピーしてコメントを自分で投稿できる手動コマンドを提示します。
• 実行サマリーに失敗を記録します。

ステップ7：実行サマリー

パイプラインの成功・失敗にかかわらず、必ず最後に構造化された実行サマリーを出力します。

### Issue Review — Run Summary
- **Issue :** #XX — [titre]
- **Remote :** GitLab / GitHub
- **Personas :** [Name (Role)] | [Name (Role)] | [Name (Role)]
- **Rounds :** 3 (ouverture + débat + convergence)
- **Anti-groupthink :** déclenché / non nécessaire
- **Verdict :** ✅ Prête / ⚠️ Ajustements / ❌ Refonte
- **Commentaire :** publié (#XX) / échec ([raison])
- **Durée totale :** [durée wall-clock]

エッジケース

最小限の Issue または空の Issue

Issue に説明がない場合、または意味のある内容がない1行のタイトルしかない場合：

1. ペルソナ会議を実行しないでください — レビューに必要な内容が不足しています。
2. 不足しているものを列挙した短いコメントを、Issue にフランス語で投稿します。

## Revue d'issue — Contenu insuffisant

Cette issue ne contient pas assez d'informations pour réaliser une revue pertinente.

### Éléments manquants
- [ ] Description détaillée du besoin ou du problème
- [ ] Critères d'acceptation
- [ ] Contexte métier (qui est impacté, quel workflow)
- [ ] [Any other specific gaps detected]

Merci de compléter l'issue puis de relancer la revue.

---
_Revue générée automatiquement par IA_

3. 同じメッセージを会話にも出力し、終了します。

クローズ済みのイシュー

イシューがクローズされている場合：

1. ユーザーに警告します：「Cette issue est fermée. Souhaitez-vous quand même lancer la revue ? (utile pour une rétrospective)」
2. **ユーザーが確認した場合：**通常どおり続行します
3. **ユーザーが辞退した場合、または返答がない場合：**停止します

投稿に失敗した場合

イシューにコメントを投稿できない場合：

• レビュー全文を会話に出力します
• 手動実行用に書式を整えたコマンドを提示します
• 失敗を実行サマリーに記録します

会議の品質ルール

ペルソナの信頼性

• 各ペルソナは、自身の役割や偏りに一貫した発言をします
• ペルソナは、抽象的な決まり文句ではなく、具体例を使います
• セキュリティエンジニアは、漠然とした「セキュリティ上の懸念」ではなく、攻撃ベクトルについて話します
• プロダクトオーナーは、コードのパターンではなく、ユーザーへの影響やリリースのタイムラインについて話します

議論の質

• 少なくとも1人のペルソナは、多数派と意見を異にする必要があります
• 議論では、具体的なトレードオフ（パフォーマンスと保守性、速度と安全性など）に言及する必要があります
• 安易な全員一致は避けます。全員がすぐに同意した場合は、集団浅慮の防止チェックが悪魔の代弁者を呼び出します
• ペルソナは、議論を通じて納得した場合、意見を変えてもかまいません

レビューの質

• レビューは漠然としたものではなく、実行可能な内容にする必要があります
• リスクには、軽減策を含める必要があります
• 次のステップは、具体的でチェックボックスにできる内容にします
• 判定は、定義された3つのレベル（ready／needs adjustments／needs rework）のいずれかにします
• 分析はフランス語で記述します（自然でプロフェッショナルな文体で、「nous」を使用）

例

例1：明確に定義された機能イシュー

User: issue-review #42

→ Fetch issue #42 (feature: add patient notification system)
→ Fetch all comments (3 comments with PO clarifications)
→ No linked branch
→ Explore codebase: notification module, patient service, event system
→ Auto-select: SOLID Alex (Backend), Whiteboard Damien (Architecte), Sprint Zero Sarah (PO), Paranoid Shug (Sécurité)
→ Run 3-round review meeting
→ Verdict: ⚠️ Nécessite des ajustements (missing acceptance criteria for notification preferences)
→ Post review comment on issue #42

例2：ブランチがリンクされたイシュー

User: issue-review https://github.com/org/repo/issues/15

→ Fetch issue #15 (bug: patient search returns duplicates)
→ Fetch comments (1 comment with reproduction steps)
→ Linked branch: fix/patient-search-duplicates — fetch diff
→ Explore codebase: search service, patient repository, index configuration
→ Auto-select: SOLID Alex (Backend), EXPLAIN PLAN Isabelle (DBA), Edge-Case Nico (QA)
→ Run 3-round review meeting
→ Verdict: ✅ Prête pour implémentation
→ Post review comment on issue #15

例3：不完全なイシュー

User: issue-review #99

→ Fetch issue #99 (title only: "Fix the thing")
→ No description, no comments
→ Skip meeting — post "contenu insuffisant" comment
→ List missing elements on issue #99

例4：クローズ済みのイシュー（振り返り）

User: issue-review #30

→ Fetch issue #30 (closed)
→ Warn user: "Cette issue est fermée. Souhaitez-vous quand même lancer la revue ?"
→ User confirms
→ Proceed with full review pipeline
→ Post review comment on issue #30

重要事項

• **GitLab や GitHub に新しいラベルを作成しないでください。**プロジェクトにすでに存在するラベルのみを使用してください。適切なラベルが存在しない場合は、ラベル付けを省略してください。
• **このスキルは分析のみを行います。**コードの実装、ブランチの作成、MR／PR の作成は行いません
• レビューコメントは常にフランス語で記述し、PO／コンサルタント向けに、必要に応じて技術的な懸念を提示します
• ブランチがリンクされていない場合も、コンテキストを把握するためにコードベースを常に調査します
• 詳細なレビューを行うため、会議は3つの完全なラウンド（冒頭、議論、収束）で進行します
• リモートの種類を特定できない場合は、gh issue comment（GitHub）をデフォルトとして使用します
• このスキルは GitLab と GitHub の両方のイシューに対応しています