Revue de PR avec Amiral et pr-review-toolkit

Contexte

Vous avez une PR ouverte et vous voulez une revue profonde : analyser la généralisabilité du projet (secrets, couplages, portabilité) ET examiner les changements de code avec le plugin pr-review-toolkit pour détecter bugs, types manquants, erreurs silencieuses.

Prérequis

• Projet git avec branches et PRs
• PR ouverte sur GitHub (ou branch locale)
• Plugin officiel Anthropic : pr-review-toolkit installé
• Accès Read au code source

Étapes

1. Invocation amiral pour revue PR

Lancez Amiral en mode review :

/ulk:amiral fork

ou

Évalue la généralisabilité et revue la PR

Amiral propose un workflow de revue.

2. Phase 1 — Cadrage et questions

Amiral pose des questions via AskUserQuestionTool :

1. Lien vers la PR (GitHub / GitLab) ?
   → https://github.com/org/repo/pull/42

2. Objectif de la PR ?
   → Ajouter authentification OAuth

3. Niveaux de nettoyage souhaité pour audit généralisabilité ?
   → Standard (secrets + références privées)

4. Utiliser pr-review-toolkit pour code review ?
   → Oui

Sortie :

=== Configuration Revue ===

🔗 PR #42 — Add OAuth authentication
📋 Branch : feature/oauth-provider
🔧 Plugins : pr-review-toolkit activé
🎯 Audit général + Code review détaillée

3. Phase 2 — Audit généralisabilité du projet

Amiral scanne le projet entier (6 dimensions) :

# Secrets & données sensibles
grep -rn "API_KEY\|PASSWORD\|SECRET" --include="*.ts" --include="*.env*" .

# Couplages propriétaires
grep -rn "company.com\|org-specific" --include="*.ts" .

# Dépendances
cat package.json | grep -A 30 "dependencies"

Rapport :

🔒 SECRETS & DONNÉES SENSIBLES
  ⚠️ Found: API_KEY hardcoded [api/oauth.ts:42]
  ⚠️ Found: DB connection string [config.ts:10]

🔗 COUPLAGES PROPRIÉTAIRES
  ✅ No org-specific branding detected

📦 DÉPENDANCES & PORTABILITÉ
  ✅ All public registries
  ⚠️ Outdated: passport (5.1.0 → 6.0.0)

SCORE GÉNÉRALISABILITÉ : 65/100 — CARÉNAGE NÉCESSAIRE

4. Phase 3 — Code review via pr-review-toolkit

Amiral déclenche le plugin officiel pour l’analyse du diff :

/pr-review-toolkit:review-pr

Le plugin analyse :

=== PR Code Review ===

📊 Changements : +245 lignes, -18 lignes
🔴 Findings détectés : 7

CRITICAL
  ❌ [oauth.ts:42] API key hardcoded (CRITICAL)
       const apiKey = "sk-proj-xxx"
       Fix: Use process.env.OAUTH_API_KEY

  ❌ [oauth.ts:55] Missing null check
       const user = getUserFromDB(id)
       user.email.toLowerCase()  // can crash if user is null
       Fix: if (!user) throw new Error(...)

HIGH
  ⚠️ [middleware/oauth.ts:10] Type any detected
       const config: any = getOAuthConfig()
       Fix: Create interface OAuthConfig

  ⚠️ [test/oauth.test.ts:5] Missing test case
       // Should test refresh token logic
       No test for token refresh scenario

MEDIUM
  🟡 [oauth.ts:70] No error handling
       const token = await provider.getToken()
       Fix: wrap in try-catch

  🟡 [oauth.ts:88] Duplicate code
       Same logic as [utils/auth.ts:42]
       Fix: Extract to shared function

  🟡 [README.md] OAuth docs outdated
       Section "Setup OAuth" references old API version
       Fix: Update docs to v6.0

5. Phase 4 — Synthèse et recommandations

Rapport synthétique :

=== REVUE PR #42 ===

📈 MÉTRIQUES
  Files changed   : 5
  Lines added     : 245
  Lines removed   : 18
  Commits         : 3

🎯 COUVERTURE CODE
  Current coverage: 64%
  PR coverage gain : +3%
  Target reached  : 67% (target: 80%)

🔍 QUALITÉ
  Bugs potentiels : 2 (null checks, error handling)
  Type issues     : 1 (any detected)
  Security issues : 1 (hardcoded secret)
  Code duplication: 1 (consolidate)

📝 DOCUMENTATION
  README updated  : ⚠️ Partial (OAuth section outdated)
  Tests           : ⚠️ Incomplete (token refresh missing)

VERDICT
  ❌ NOT APPROVED — Blocker issues must be fixed
     1. Remove hardcoded API key
     2. Add null checks
     3. Fix type annotations
     Then re-request review.

6. Phase 5 — Génération des tâches

Amiral crée une checklist de corrections dans docs/pr-review/pr-42-findings.md :

## PR #42 Review Findings

### 🔴 BLOCKERS (Must fix)

#### REV-001 : Remove hardcoded API key
- [ ] Replace `const apiKey = "sk-proj-xxx"` with `process.env.OAUTH_API_KEY`
- [ ] Add OAUTH_API_KEY to .env.example
- [ ] Verify secret rotation in CI/CD

#### REV-002 : Add missing null checks
- [ ] [oauth.ts:55] Null check before `user.email`
- [ ] [oauth.ts:70] Try-catch around token fetch
- [ ] Test with null/undefined inputs

### 🟠 RECOMMENDED (Before merge)

#### REV-003 : Fix type annotation
- [ ] Replace `config: any` with typed interface
- [ ] Create `interface OAuthConfig { ... }`
- [ ] Verify all properties typed

#### REV-004 : Add missing test case
- [ ] Test token refresh scenario
- [ ] Verify token expiry handling
- [ ] Test concurrent refresh attempts

### 🟡 NICE-TO-HAVE (Consider)

#### REV-005 : Remove code duplication
- [ ] Extract common auth logic to [utils/auth.ts]
- [ ] Use shared function from both [oauth.ts] and [middleware/oauth.ts]

#### REV-006 : Update documentation
- [ ] Update README OAuth section (current: v5 → target: v6)
- [ ] Add setup example for new API

---

**Reviewer confidence** : 85% (pr-review-toolkit + amiral audit)
**Estimated fix time** : 2-4 hours
**Re-review needed** : Yes, after blockers fixed

7. Approche par étapes

Pour chaque finding, proposer un workflow :

💡 Fixing the PR

1. Checkout branch locally
   git checkout feature/oauth-provider

2. Fix CRITICAL issues
   [ ] REV-001 : Remove secret
   [ ] REV-002 : Add null checks
   npm test  (verify no regression)
   git commit -m "fix: remove hardcoded key, add safety checks"

3. Run pr-review-toolkit again
   /pr-review-toolkit:review-pr
   (should show 0 critical findings)

4. Merge when all blockers resolved
   → Re-request review on GitHub

Variantes

• Variante A — Audit uniquement : Skip plugin, just amiral audit
• Variante B — Code review only : Just /pr-review-toolkit:review-pr, skip generalizability
• Variante C — Quick review : Mode compact (10-min summary)
• Variante D — Continuous : Schedule reviews on all PRs via /schedule pr-review-automation

Agents enchaînés

Flux typique : amiral (41) audit général → /pr-review-toolkit code review → vision (05) follow-up audit.

Troubleshooting

Symptôme	Cause probable	Résolution
PR non trouvée	URL incorrecte	Vérifier lien GitHub
Plugin non disponible	pr-review-toolkit non installé	Installer via marketplace
Secrets détectés	False positive	Réviser manuellement
Review très long	Gros PR (> 400 lignes)	Split PR en smaller chunks

Voir aussi

• agents/audit/41-amiral.md — agent complet
• agents/audit/05-vision.md — audit code détaillé
• plugins-protocol.md — pr-review-toolkit documentation