Claude-config/commands/full-project-review.md

---
name: full-project-review
description: Use when the user asks for a complete project review, code audit, educational review, codebase health check, or intern/junior review. Triggers on words like "review", "audit", "revue", "review de projet", "code quality check". Produces a structured REVIEW.md with prioritized findings and a TICKETS.md with actionable fix tickets.
---

# Full Project Review

## Overview

Audit complet et educatif d'un projet. Produit un `REVIEW.md` structure couvrant securite, bugs, dead code, incoherences, documentation, frontend, CSS, CI/CD -- avec explications pedagogiques et tableau de priorites. Genere ensuite un `TICKETS.md` avec des tickets actionnables pour corriger les findings.

**Principe :** Chaque finding explique le probleme, pourquoi c'est un probleme, et comment le corriger. Pas juste une liste de bugs -- un outil d'apprentissage.

## When to Use

- L'utilisateur demande une "review", "audit", "revue de code", "code quality check"
- Review educative pour un junior/stagiaire
- Health check avant mise en production
- Onboarding sur un nouveau projet

## Process

```dot
digraph review_flow {
  rankdir=TB;
  "1. Lire CLAUDE.md, AGENTS.md, README" -> "2. Lancer 2 agents en parallele";
  "2. Lancer 2 agents en parallele" -> "3. Lire les fichiers critiques identifies";
  "3. Lire les fichiers critiques identifies" -> "4. Rediger REVIEW.md structure";
  "4. Rediger REVIEW.md structure" -> "5. Generer TICKETS.md";
  "5. Generer TICKETS.md" -> "6. Resume au user";
}
```

### Phase 1 -- Comprendre le contexte

**REQUIRED:** Invoke `superpowers:brainstorming` if user requirements are unclear (scope of review, educational vs production audit, specific concerns).

Lire dans cet ordre :
1. `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` -- les regles du projet
2. `README.md` -- ce que le projet pretend etre
3. `package.json` / `nuxt.config.ts` / `pyproject.toml` -- stack technique
4. `.env.example` -- variables d'environnement
5. `.gitignore`, CI workflows

### Phase 2 -- Lancer 2 agents specialises en parallele

**REQUIRED:** Use `superpowers:dispatching-parallel-agents` pattern for this phase.

**Agent 1 : Exploration profonde** (`feature-dev:code-explorer`)

Prompt :
```
I need a comprehensive deep-dive review of this entire project.

Explore EVERYTHING and report back with detailed findings. Focus on:

1. **Project structure** -- all directories, file organization
2. **Documentation quality** -- README.md, CLAUDE.md, AGENTS.md, any .md files, comments quality
3. **Configuration files** -- package.json, framework config, tsconfig, .env.example, docker files, CI/CD
4. **Server-side code** -- all backend files (API routes, middleware, plugins, utils, config)
5. **Frontend code** -- pages, components, composables, layouts, entry point
6. **Security practices** -- auth, input validation, env vars handling, shell command safety (execFile vs shell execution)
7. **Code quality** -- dead code, unused imports, inconsistent patterns, error handling
8. **Dependencies** -- deps list, unnecessary deps, version alignment
9. **Git hygiene** -- .gitignore, what is tracked that should not be

Read ALL files you can find. Be thorough. Report raw findings with file paths and line numbers. Do not filter -- I want everything, good and bad.
```

**Agent 2 : Security and code quality** (`feature-dev:code-reviewer`)

Prompt :
```
Do a thorough security and code quality review of this project.

Focus specifically on:

1. **Security vulnerabilities** -- injection risks (shell, SQL, XSS), auth bypass, hardcoded secrets, SSRF, path traversal
2. **Error handling** -- uncaught exceptions, missing try/catch, error info leaks
3. **API design** -- inconsistent responses, missing validation, HTTP status codes
4. **Authentication** -- middleware bypass possibilities, token handling, cookie security
5. **Input validation** -- all user inputs, query params, body params
6. **Performance issues** -- memory leaks, blocking operations, missing timeouts
7. **TypeScript usage** -- any types, missing types, type safety issues
8. **Frontend issues** -- XSS risks, reactive state issues, missing loading/error states

Read all server files, all components, all pages. Be thorough and report with file paths and line numbers. Report confidence levels for each finding.
```

### Phase 3 -- Lire les fichiers critiques identifies

After agents return, manually read each flagged file to:
- Verify findings (no false positives)
- Understand full context (agents can miss nuances)
- Identify cross-cutting patterns

### Phase 4 -- Rediger REVIEW.md

**REQUIRED:** Use `superpowers:verification-before-completion` before declaring the review complete -- verify key findings by re-reading the actual code.

### Phase 5 -- Generer TICKETS.md

Apres le REVIEW.md, generer un fichier `TICKETS.md` contenant des tickets actionnables pour corriger les findings. Ce document est destine a un developpeur (junior, stagiaire, ou l'auteur du code) qui va implementer les corrections.

**Chaque ticket doit contenir :**
1. Un identifiant unique (T-001, T-002, ...)
2. Un titre court et clair
3. **Pourquoi** -- une phrase expliquant le probleme (sans jargon inutile)
4. **A faire** -- les etapes concretes, avec le code exact avant/apres quand c'est pertinent
5. **Fichiers** -- la liste des fichiers concernes

**Regles de redaction des tickets :**
- Grouper par priorite (P0, P1, P2, P3) dans le meme ordre que le REVIEW.md
- Un ticket = un changement atomique commitable independamment
- Si un finding du REVIEW.md genere plusieurs changements dans des fichiers differents mais lies (ex: renommer une variable partout), c'est UN seul ticket
- Si un finding est purement informatif et n'a pas d'action concrete, ne pas creer de ticket
- Inclure le code exact a modifier (avant/apres) pour les tickets P0 et P1 -- le developpeur ne doit pas avoir a deviner
- Pour les tickets P2/P3, une description claire suffit si le changement est evident
- Terminer par un tableau recapitulatif avec estimation de temps par priorite
- Suggerer une convention de commit : `fix(T-XXX): description courte`

**Niveau de langage :**
- Ecrire pour un stagiaire BTS SIO 2eme annee (niveau debutant-intermediaire)
- Pas de jargon sans explication : si on dit "injection SQL", expliquer en une phrase ce que ca veut dire
- Les etapes "A faire" doivent etre des instructions pas-a-pas qu'on peut suivre sans deviner
- Montrer le code exact avant/apres (copier-coller ready) pour les P0 et P1
- Si une commande git est necessaire, donner la commande complete
- Privilegier les explications concretes ("si quelqu'un trouve ce lien, il peut poster des messages dans ton Discord") plutot qu'abstraites ("vecteur d'attaque via endpoint non authentifie")

**Structure du TICKETS.md :**

```markdown
# Tickets correctifs -- Projet {NOM}

> Liste de taches issues de la review du {DATE}.
> Chaque ticket est autonome : contexte, ce qu'il faut faire, fichiers concernes.
> Commence par les P0, puis P1, etc.

---

## P0 -- Urgents (securite)

### T-001 -- {Titre}
**Pourquoi :** {explication courte}
**A faire :**
1. {etape avec code avant/apres}
2. {etape}
**Fichiers :** `chemin/fichier.sh`

---

## P1 -- Importants
...

## P2 -- Documentation
...

## P3 -- Nice to have
...

## Resume

| Priorite | Tickets | Estimation |
|----------|---------|------------|
| **P0** | T-001 a T-00X | ~Xh |
| **P1** | T-00X a T-00X | ~Xh |
| **P2** | T-00X a T-00X | ~Xh |
| **P3** | T-00X a T-00X | ~Xmin |
| **Total** | XX tickets | ~Xh |

> Commence par T-001 -- c'est le plus urgent.
> Pour chaque ticket, fais un commit dedie avec le numero du ticket dans le message (ex: `fix(T-001): description`).
```

## Structure du REVIEW.md

```markdown
# Review complete -- Projet {NOM}

> Audit educatif du projet. Chaque point explique le probleme, pourquoi c'est un probleme, et comment le corriger.
> Document genere le {DATE}.

---

## Table des matieres
1. Securite
2. Bugs fonctionnels
3. Code mort et violations des regles projet
4. Incoherences de patterns
5. Documentation et configuration
6. Frontend et UX
7. CSS et design system
8. CI/CD et dependances
9. Bonnes pratiques a retenir

---

## 1. Securite
### 1.1 {GRAVITE} -- {Titre court}
**Fichier :** `chemin/fichier.ts` ligne XX
{Explication du probleme}
{Pourquoi c'est grave}
{Code exemple avant/apres si pertinent}
**Correction :** {Solution concrete}

...

## 9. Bonnes pratiques a retenir
### Ce qui est bien fait dans le projet
{Liste des points positifs -- toujours inclure, la review doit etre equilibree}

### Les regles a graver
{10 regles tirees des findings, numerotees}

---

## Resume par priorite
| Priorite | # | Probleme | Fichier |
|----------|---|----------|---------|
| **P0** | x.x | ... | `fichier:ligne` |
| **P1** | x.x | ... | `fichier:ligne` |
| **P2** | x.x | ... | `fichier:ligne` |
| **P3** | x.x | ... | `fichier:ligne` |
```

## Niveaux de gravite

| Label | Signification | Exemples |
|-------|--------------|----------|
| **CRITIQUE** | Faille de securite exploitable ou bug bloquant | Injection shell, auth bypass, crash en prod |
| **IMPORTANT** | Bug silencieux ou risque serieux | NaN dans une commande, undefined non garde, dead code trompeur |
| **MOYEN** | Probleme reel mais impact limite | Fuite de processus, timeout manquant, validation incomplete |
| **MINEUR** | Polish, coherence, dette technique | Typo CSS, import inconsistant, nom trompeur |

## Priorites de resume

| Priorite | Critere |
|----------|---------|
| **P0** | Securite exploitable + bugs qui cassent des fonctionnalites |
| **P1** | Bugs silencieux + violations des regles projet + risques operationnels |
| **P2** | Incoherences de patterns + documentation cassee + config incorrecte + CI manquante |
| **P3** | Dead code mineur + polish frontend + typos CSS |

## Checklist des categories a couvrir

Ne pas oublier de verifier chacun de ces points :

### Securite
- [ ] Execution de commandes : `execFile` (safe) vs execution shell (injectable)
- [ ] Input validation sur tous les parametres utilisateur (query, body, headers)
- [ ] Auth : bypass possible ? Token/cookie securise ? Login requis ?
- [ ] Secrets dans le code source ou dans la config publique du framework
- [ ] `robots.txt` -- ouvert ou ferme pour un outil interne ?
- [ ] Limite de taille sur les uploads
- [ ] Timeout sur les fetch/requetes sortantes
- [ ] Informations d'infrastructure dans les fichiers versionnes (hostnames, usernames, chemins absolus)
- [ ] Processus enfants nettoyes en cas de deconnexion client
- [ ] Chemins hardcodes (`/home/username/...`) au lieu de `$HOME` ou variables d'env

### Bugs fonctionnels
- [ ] Variables d'environnement non definies -> `undefined`, `NaN`, comportement silencieux
- [ ] Code qui s'ecrase lui-meme (double assignation)
- [ ] Incoherences de nommage entre fichiers (tiret vs underscore, etc.)
- [ ] Fonctions dupliquees entre fichiers
- [ ] Types manquants ou `any` implicite

### Code mort
- [ ] Fonctions declarees mais jamais appelees
- [ ] Variables assignees mais jamais lues dans le template/output
- [ ] Wrappers d'une ligne qui n'ajoutent rien
- [ ] Fallbacks legacy pour des configs obsoletes
- [ ] CSS pour des classes qui n'existent plus
- [ ] `computed()` sur des constantes

### Incoherences
- [ ] Imports : melange de patterns pour le meme module
- [ ] Auto-imports vs imports explicites dans le meme fichier
- [ ] Indentation (2 vs 4 espaces) entre fichiers
- [ ] Acces aux env vars : runtimeConfig vs process.env direct vs shims

### Documentation
- [ ] README : formatage casse, sections manquantes, commandes incoherentes
- [ ] `.env.example` : commentaires explicatifs presents ?
- [ ] `package.json` : nom correct ? champ `engines` ?
- [ ] `.env` centralise et reference par chemin relatif dans les scripts
- [ ] Doc SSH : meme cle/user/host dans toutes les commandes d'un bloc

### Frontend
- [ ] Etat actif sur la navigation (highlight de la page courante)
- [ ] HTML duplique au lieu de composants partages
- [ ] Texte statique trompeur (ex: "Production" hardcode)
- [ ] Imports depuis `server/` dans du code client
- [ ] Null guards sur les donnees dynamiques

### CI/CD
- [ ] Build et lint AVANT la release
- [ ] Version Node alignee entre README, CI, et `package.json`
- [ ] Dependances installees mais non utilisees

## Regles de redaction

1. **Toujours inclure les points positifs** -- une review 100% negative est demotivante et inexacte
2. **Chaque finding = probleme + pourquoi + correction** -- educatif, pas juste une liste
3. **Code exemple quand c'est utile** -- avant/apres, pas juste le mauvais code
4. **Fichier et ligne pour chaque point** -- le lecteur doit pouvoir naviguer directement
5. **Langue du projet** -- si le projet est en francais, la review est en francais
6. **Pas de faux positifs** -- lire le fichier avant de signaler, comprendre le contexte
7. **Tableau de priorites en fin de document** -- vue d'ensemble rapide pour le decideur

## Skills superpowers a invoquer

| Phase | Skill | Pourquoi |
|-------|-------|----------|
| Phase 1 | `superpowers:brainstorming` | Si le scope de la review n'est pas clair |
| Phase 2 | `superpowers:dispatching-parallel-agents` | Pour lancer les 2 agents en parallele |
| Phase 4 | `superpowers:verification-before-completion` | Verifier les findings avant de livrer |
| Phase 5 | _(pas de skill)_ | Generer TICKETS.md a partir du REVIEW.md |
| Apres | `superpowers:requesting-code-review` | Si l'utilisateur demande ensuite de corriger les findings |

## Common Mistakes

- **Signaler un probleme sans lire le fichier** -- les agents peuvent se tromper, toujours verifier
- **Oublier les positifs** -- demotive l'equipe, semble partial
- **Review trop longue sans structure** -- le tableau de priorites est essentiel
- **Suggestions non-actionables** -- "ameliorez la securite" n'aide personne, "remplacez X par Y dans `fichier:ligne`" aide
- **Ignorer AGENTS.md/CLAUDE.md** -- le projet a ses propres regles, les findings doivent les referencer