issue-review

Issue 审查

使用专家角色，对 GitLab 或 GitHub issue 进行完全自主的多角度审查。此技能会获取 issue 上下文、探索相关代码库、开展 3 轮角色会议（开场陈述、辩论、加权收敛），并直接在 issue 上发布结构化审查评论，全程无需征求用户确认。

前置条件

• 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 进行“issue 审查”或“issue review”
• 说“issue-review #42”或“issue-review ”
• 希望在实现之前从多个角度分析一个 issue
• 希望就某个 issue 的可行性、完整性和风险获得结构化意见

核心原则

1. 完全自主

• 整个流程无需向用户提问（已关闭的 issue 除外——参见边缘情况）
• 根据 issue 内容分析自动选择角色
• 直接在 issue 上发布审查评论

2. 多角度分析

• 各角色审查可行性、完整性、风险和架构
• 进行完整的 3 轮讨论，确保真正的辩论和更深入的分析
• 每个角色都提供真正不同的观点

3. 深入理解上下文

• 此技能会读取完整的 issue：描述、所有评论、标签
• 如果关联了分支，则分析该分支的差异
• 自动探索现有代码库，为各角色提供充分的上下文

4. 仅做分析

• 此技能不会实现任何内容
• 它会生成包含可执行后续步骤的审查结果
• 团队阅读分析后决定采取何种行动

工作流

步骤 1：识别并获取 issue

1. 解析用户输入，提取 issue 引用：

   • Issue 编号：#42
   • 完整 URL：https://gitlab.example.com/group/project/-/issues/42 或 https://github.com/owner/repo/issues/42
   • 如果未找到有效的 issue 引用，请用户提供

2. 检测远程仓库类型：

   • 运行 git remote -v，确定远程仓库使用 GitLab 还是 GitHub
   • 保存此信息，供步骤 7（发布评论）使用

3. 获取 issue 详情：

   • GitLab： glab issue view <iid> — 标题、描述、标签、状态
   • GitHub： gh issue view <number> — 标题、正文、标签、状态

4. 获取所有 issue 评论：

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

5. 检查 issue 状态：

   • 如果 issue 已关闭，提醒用户并在继续之前征求确认（参见边缘情况）
   • 如果 issue 仍打开，正常继续

6. 检查内容是否过少（参见边缘情况）：

   • 如果 issue 没有描述，或只有一行标题且不包含有意义的内容，则跳过会议，并发布简短评论，列出缺少的内容

步骤 2：收集完整上下文

Issue 上下文

• Issue 标题、描述及所有评论（在步骤 1 中收集）
• 标签和里程碑（用于领域判断）

关联分支上下文

1. 检查是否有关联分支：
   • GitLab： 通过 glab api /projects/:id/issues/:iid/related_merge_requests 检查 issue 是否有关联的合并请求，或在 issue/评论中查找分支引用
   • 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（产品负责人）、Whiteboard Damien（架构师）
安全 / 身份验证 / 访问控制	Paranoid Shug（安全）、RGPD Raphaël（数据保护官）、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（互操作产品负责人）、HL7 Victor（互操作开发）、SOLID Alex（后端）
Legacy / Uniface / 现代化	Legacy Larry（Uniface）、Whiteboard Damien（架构师）、SOLID Alex（后端）
测试 / 质量 / 回归	Edge-Case Nico（QA）、SOLID Alex（后端）、Pipeline Mo（DevOps）
产品 / 功能 / UX 决策	Sprint Zero Sarah（产品负责人）、Pixel-Perfect Hugo（前端）、Figma Fiona（UX/UI）、Whiteboard Damien（架构师）
医疗 / 临床工作流	Dr. Workflow Wendy（医疗）、Sprint Zero Sarah（产品负责人）、RGPD Raphaël（数据保护官）
RGPD / 个人数据 / 合规	RGPD Raphaël（数据保护官）、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（产品负责人）、Edge-Case Nico（QA）

如果主题涉及多个领域，请选择最相关的 3–4 个角色。

**角色的完整列表及其职责、视角和偏见：**参见 reference/personas.md。

开始会议前，先宣布所选角色及其职责。

第 4 步：开展评审会议

会议将使用子 Agent，让每个角色独立并行开展评审。评审会议共进行 3 轮，以深入讨论。

重要：使用 Agent 工具，为每个角色分别启动一个子 Agent。

第 1 轮：开场陈述（并行子 Agent）

使用 Agent 工具，并行为每个角色启动一个子 Agent。每个子 Agent 接收以下内容：

1. 问题标题和描述
2. 收集到的所有上下文（评论、分支差异、代码库片段）
3. 角色的身份提示词

子 Agent 提示词模板：

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.

在同一条消息中启动所有角色的子 Agent，使其并行运行。使用 subagent_type: "general-purpose"，并采用 "Review persona: {name}" 这类简短描述。

收集所有观点，并以引言形式展示：

SOLID Alex（高级后端工程师）：“我认为……”

反群体思维检查

收集完第一轮回复后，评估共识程度：

1. 检查所有角色是否都对同一项评估达成一致（结论相同，没有实质性分歧）
2. 如果共识度过高（所有角色都同意，且没有提出异议）：
   • 启动一个额外的子 Agent，扮演唱反调者：

     你是一名正在审查某个问题的唱反调者。
     
     所有审查者都同意这项评估：{consensus_summary}
     
     你的任务：针对这项共识提出尽可能有力的反对论据。
     - 有什么风险是所有人都没提到的？
     - 他们都基于什么假设，而这个假设可能是错误的？
     - 有什么边缘情况或故障模式被过快地排除？
     
     请具体、明确地说明。引用真实的故障场景。
     这是研究任务——不要编写或编辑任何文件。
     

   • 在分析中纳入不同意见
3. **如果已经存在实质性分歧：**直接进入第二轮

第二轮：辩论与质疑（并行子 Agent）

启动第二轮并行子 Agent——每个角色对应一个。每个子 Agent 会收到：

1. 问题详情
2. 第一轮的全部开场陈述（所有角色）
3. 该角色的身份提示词

第二轮子 Agent 提示词模板：

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.

在一条消息中启动第二轮的所有角色子 Agent。

**本轮应当产生真正的观点交锋。**如果所有子 Agent 都达成一致，就追加提示，让其中一个 Agent 针对多数立场扮演唱反调者。

第三轮：加权收敛

收集完所有第二轮回复后，由你（主持人，而非子 Agent）综合讨论结果：

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 没有描述，或者只有一句标题且没有任何有意义的内容：

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. **如果用户拒绝或未回复：**停止

发布失败

如果无法在问题中发布评论：

• 在对话中输出完整评审内容
• 提供预格式化的手动命令
• 在运行摘要中记录失败情况

会议质量规则

角色真实性

• 每个角色的发言应始终符合其职责和立场
• 角色应使用具体示例，而非抽象空话
• 安全工程师应讨论攻击向量，而非含糊地谈论“安全问题”
• 产品负责人应讨论对用户的影响和交付时间表，而非代码模式

辩论质量

• 至少有一个角色必须与多数人意见相左
• 论据必须涉及具体的权衡（性能与可维护性、速度与安全性）
• 避免虚假的共识——如果所有人过快达成一致，则触发反从众检查，由唱反调者提出异议
• 如果论据有说服力，角色可以在辩论过程中改变想法

评审质量

• 评审必须具有可操作性，不能含糊
• 风险必须包含缓解策略
• 后续步骤必须具体且可勾选
• 结论必须是三个定义级别之一（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 问题