issue-review

What this skill does

# Issue Review

Run a fully autonomous multi-angle review of a GitLab or GitHub issue using expert personas. The skill fetches issue context, explores the relevant codebase, runs a 3-round persona meeting (opening statements, debate, weighted convergence), and posts a structured review comment directly on the issue — all without asking the user for confirmation.

## Prerequisites

- **gh** (GitHub CLI): required when the project uses GitHub — install from https://cli.github.com or `brew install gh`
- **glab** (GitLab CLI): required when the project uses GitLab — install from https://gitlab.com/gitlab-org/cli or `brew install glab`

## When to Use This Skill

Activate when the user:
- Demande une « revue d'issue » ou « issue review » sur une issue
- Dit « issue-review #42 » ou « issue-review <URL> »
- Veut analyser une issue sous plusieurs angles avant implémentation
- Veut un avis structuré sur la faisabilité, la complétude et les risques d'une issue

## Core Principles

### 1. Full Autonomy
- The entire pipeline runs without asking any user questions (except for closed issues — see Edge Cases)
- Persona selection is automatic based on issue content analysis
- The review comment is posted directly on the issue

### 2. Multi-Angle Analysis
- Personas review feasibility, completeness, risks, and architecture
- 3 full rounds ensure genuine debate and richer analysis
- Each persona brings a genuinely different viewpoint

### 3. Contextual Depth
- The skill reads the full issue: description, all comments, labels
- If a branch is linked, the branch diff is analyzed
- The existing codebase is explored automatically to give personas informed context

### 4. Analytical Only
- This skill does NOT implement anything
- It produces a review with actionable next steps
- The team reads the analysis and decides what to do

## Workflow

### Step 1: Identify and Fetch the Issue

1. **Parse the user's input** to extract the issue reference:
   - Issue number: `#42`
   - Full URL: `https://gitlab.example.com/group/project/-/issues/42` or `https://github.com/owner/repo/issues/42`
   - If no valid issue reference is found, ask the user to provide one

2. **Detect the remote repository type:**
   - Run `git remote -v` to determine if the remote is GitLab or GitHub
   - Store this for Step 7 (posting the comment)

3. **Fetch the issue details:**
   - **GitLab:** `glab issue view <iid>` — title, description, labels, state
   - **GitHub:** `gh issue view <number>` — title, body, labels, state

4. **Fetch all issue comments:**
   - **GitLab:** `glab issue note list <iid>` or `glab api /projects/:id/issues/:iid/notes`
   - **GitHub:** `gh issue view <number> --comments`

5. **Check issue state:**
   - If the issue is **closed**, warn the user and ask for confirmation before proceeding (see Edge Cases)
   - If the issue is **open**, proceed normally

6. **Check for minimal content** (see Edge Cases):
   - If the issue has no description or only a one-line title with no meaningful content, skip the meeting and post a short comment listing what's missing

### Step 2: Gather Full Context

#### Issue Context
- Issue title, description, and all comments (collected in Step 1)
- Labels and milestones (for domain detection)

#### Linked Branch Context
1. **Check for linked branches:**
   - **GitLab:** Check the issue for related merge requests via `glab api /projects/:id/issues/:iid/related_merge_requests` or look for branch references in the issue/comments
   - **GitHub:** Check for linked pull requests via `gh pr list --search "<issue reference>"`
2. **If a branch exists:**
   - Fetch the diff: `git diff main...<branch>` (or the appropriate base branch)
   - Include the diff summary and key file changes in the persona context

#### Codebase Context
1. **Analyze the issue content** to identify which parts of the codebase are relevant:
   - File paths, module names, function names, or components mentioned in the issue or comments
   - Domain keywords that map to specific directories or files
2. **Explore the codebase** — read relevant files to understand the current state:
   - Use Glob and Grep to find related files
   - Read the most relevant files (prioritize files explicitly mentioned, then files in related modules)
   - Understand existing patterns, architecture, and conventions
3. **Build a context summary** for the personas including:
   - Issue content (description + comments)
   - Linked branch diff (if any)
   - Relevant codebase snippets and architecture overview

### Step 3: Auto-Select Personas

Automatically select 3-4 personas based on the issue content, labels, and domain. Use these heuristics:

| Le sujet concerne... | Personas auto-sélectionnés |
|---------------------|---------------------|
| Backend / API / base de données | SOLID Alex (Backend), Whiteboard Damien (Architecte), EXPLAIN PLAN Isabelle (DBA Oracle) |
| Frontend / UI / UX | Pixel-Perfect Hugo (Frontend), Figma Fiona (UX/UI), Sprint Zero Sarah (PO), Whiteboard Damien (Architecte) |
| Sécurité / auth / contrôle d'accès | Paranoid Shug (Sécurité), RGPD Raphaël (DPO), SOLID Alex (Backend), Whiteboard Damien (Architecte) |
| Infrastructure / déploiement / CI-CD | Pipeline Mo (DevOps), SOLID Alex (Backend), Whiteboard Damien (Architecte) |
| Données / migration / ETL | Schema JB (Data), EXPLAIN PLAN Isabelle (DBA Oracle), Whiteboard Damien (Architecte) |
| Interopérabilité / HL7 / FHIR / HPK | RFC Santiago (PO Interop), HL7 Victor (Dev Interop), SOLID Alex (Backend) |
| Legacy / Uniface / modernisation | Legacy Larry (Uniface), Whiteboard Damien (Architecte), SOLID Alex (Backend) |
| Tests / qualité / régression | Edge-Case Nico (QA), SOLID Alex (Backend), Pipeline Mo (DevOps) |
| Produit / fonctionnalité / décision UX | Sprint Zero Sarah (PO), Pixel-Perfect Hugo (Frontend), Figma Fiona (UX/UI), Whiteboard Damien (Architecte) |
| Santé / workflows cliniques | Dr. Workflow Wendy (Santé), Sprint Zero Sarah (PO), RGPD Raphaël (DPO) |
| RGPD / données personnelles / conformité | RGPD Raphaël (DPO), Paranoid Shug (Sécurité), Whiteboard Damien (Architecte) |
| BI / tableaux de bord / reporting / finance / comptabilité | Dashboard Estelle (BI Finance), Pixel-Perfect Hugo (Frontend), EXPLAIN PLAN Isabelle (DBA Oracle), Whiteboard Damien (Architecte) |
| Full-stack / sujet transverse | Whiteboard Damien (Architecte), SOLID Alex (Backend), Sprint Zero Sarah (PO), Edge-Case Nico (QA) |

Si le sujet couvre plusieurs domaines, choisir les 3-4 personas les plus pertinents.

**Pool complet des personas avec rôles, perspectives et biais :** see `reference/personas.md`.

**Announce the selected personas and their roles before starting the meeting.**

### Step 4: Run the Review Meeting

The meeting uses sub-agents to run each persona independently and in parallel. The review meeting runs 3 full rounds for depth.

**IMPORTANT: Use the Agent tool to launch each persona as a separate sub-agent.**

#### Round 1: Opening Statements (Parallel Sub-Agents)

Launch one sub-agent per persona **in parallel** using the Agent tool. Each sub-agent receives:

1. The **issue title and description**
2. All **context** gathered (comments, branch diff, codebase snippets)
3. The persona's **identity prompt**

**Sub-agent prompt template:**

```
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? Wha