Examiner la documentation

Cette compétence exécute une boucle d'évaluation et d'amélioration sur un fichier de documentation.

Cible : $ARGUMENTS

Compétences pertinentes : write-docs

Aperçu du flux de travail

┌──────────────────────────────────────────────────────────────┐
│  INITIALISER : Créer un fichier d'état pour suivre les      │
│  problèmes                                                   │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│  ÉVALUER (en parallèle)                                      │
│  ┌─────────────────────┐    ┌─────────────────────────────┐  │
│  │ Agent de style      │    │ Agent de contenu            │  │
│  │ (lisibilité+voix)   │    │ (complétude+précision)      │  │
│  └─────────────────────┘    └─────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│  METTRE À JOUR L'ÉTAT : Ajouter les nouveaux problèmes,     │
│  vérifier les problèmes corrigés                             │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│  RÉSUMER : Présenter les résultats, demander l'étape suivante│
└──────────────────────────────────────────────────────────────┘
                              ↓
           ┌──────────────────┼──────────────────┐
           ↓                  ↓                  ↓
    [Utilisateur :       [Utilisateur :    [Utilisateur :
     améliorer]          compléter]         terminé]
           ↓                  ↓                  ↓
┌──────────────────┐  ┌──────────────────┐    SORTIE
│  AMÉLIORER       │  │  COMPLÉTER       │
│  (corriger les   │  │  (corriger tout, │
│  problèmes)      │  │   puis sortir)   │
└──────────────────┘  └──────────────────┘
           ↓                  ↓
  BOUCLE → ÉVALUER         SORTIE

Fichier d'état

Créer un fichier d'état dans le répertoire du scratchpad pour suivre tous les problèmes au fil des cycles. Cela évite de redécouvrir les mêmes problèmes et permet de vérifier les corrections.

Chemin : <scratchpad>/review-<filename>.md

Format :

# Suivi d'examen : [filename]

## Suivi des problèmes

Valeurs de statut : `pending` | `fixed` | `verified-fixed` | `not-fixed` | `wont-fix`

| ID  | Problème      | Type                         | Statut         | Cycle | Notes            |
| --- | ------------- | ---------------------------- | -------------- | ----- | ---------------- |
| 1   | [description] | Style/Accuracy/Completeness  | pending        | 1     | [détails]        |
| 2   | [description] | Accuracy                     | verified-fixed | 1     | Corrigé au cycle 1 |
| 3   | [description] | Completeness                 | wont-fix       | 2     | Hors du champ    |

## Historique des cycles

### Cycle 1

- Style : X/10, Voix : X/10, Complétude : X/10, Précision : X/10
- **Total : X/40**

Définitions des statuts :

• pending : Problème découvert, pas encore traité
• fixed : L'agent d'amélioration prétend l'avoir corrigé, nécessite une vérification
• verified-fixed : L'évaluation a confirmé que la correction a été appliquée correctement
• not-fixed : L'évaluation a constaté que la correction n'a pas été appliquée correctement
• wont-fix : Fausse alerte, hors du champ d'application, ou intentionnel (par ex., problèmes de complétude qui nécessitent une expansion de la documentation)

Étape 1 : Évaluation initiale

Pour le premier cycle, lancer deux sous-agents en parallèle à l'aide de l'outil Task :

// Message unique avec deux appels à l'outil Task :
Task(subagent_type="general-purpose", model="opus", prompt="Style evaluation...")
Task(subagent_type="general-purpose", model="opus", prompt="Content evaluation...")

Invite de l'agent de style (cycle 1)

Évaluer le style de la documentation pour : $ARGUMENTS

Lire les guides partagés relatifs au répertoire de cette compétence, puis lire le document cible :
1. `../shared/writing-guide.md`
2. `../shared/docs-guide.md`
3. $ARGUMENTS

Noter ces dimensions (0-10) :

LISIBILITÉ - À quel point l'écriture est-elle claire et facile à comprendre ?
- Phrases claires et directes
- Flux logique entre les sections
- Utilisation appropriée des extraits de code et des liens
- Pas de jargon inutile

VOIX - À quel point suit-elle le guide de rédaction ?
- Affirmations confiantes (pas de réserves)
- Voix active, temps présent
- Pas de signatures d'écriture IA (importance creuse, gérondifs traînants, transitions formulaïques)
- Ton approprié (expert-to-developer)
- Titres en casse de phrase

Important ! Inclure autant de corrections de haute priorité que nécessaire.

Retourner dans ce format exact :

RAPPORT DE STYLE : [filename]

LISIBILITÉ : [score]/10
- [problème ou force spécifique]
- [problème ou force spécifique]

VOIX : [score]/10
- [problème ou force spécifique]
- [problème ou force spécifique]

CORRECTIONS PRIORITAIRES :
1. [Problème de style le plus important]
2. [Deuxième plus important]
3. [Troisième plus important]
4. ...

Invite de l'agent de contenu (cycle 1)

Évaluer le contenu de la documentation pour : $ARGUMENTS

Lire $ARGUMENTS, puis vérifier les affirmations par rapport au code source dans packages/editor/ et packages/tldraw/.

Noter ces dimensions (0-10) :

COMPLÉTUDE - À quel point la couverture est-elle approfondie ?
- La vue d'ensemble établit l'objectif avant le mécanisme
- Les concepts clés sont expliqués avec suffisamment de profondeur
- Des extraits de code illustratifs si nécessaire
- Liens vers des exemples pertinents dans apps/examples (si applicable)

PRÉCISION - Le contenu technique est-il correct ?
- Les extraits de code sont syntaxiquement corrects et utilisent des API valides
- Les références API correspondent à l'implémentation réelle
- Le comportement décrit correspond au code
- Pas d'informations obsolètes

Pour les problèmes de précision, inclure les références fichier:ligne au code source.

Important ! Inclure autant de corrections de haute priorité que nécessaire. Veiller à signaler tous les problèmes de précision.

Retourner dans ce format exact :

RAPPORT DE CONTENU : [filename]

COMPLÉTUDE : [score]/10
- [problème ou force spécifique]
- [problème ou force spécifique]

PRÉCISION : [score]/10
- [problème spécifique avec référence fichier:ligne si inexact]
- [problème ou force spécifique]

CORRECTIONS PRIORITAIRES :
1. [Problème de contenu le plus important]
2. [Deuxième plus important]
3. [Troisième plus important]
4. ...

Après le cycle 1, créer le fichier d'état avec tous les problèmes découverts.

Étape 2 : Résumer et demander à l'utilisateur

Après le retour des deux agents, synthétiser leurs rapports dans un résumé :

## Évaluation : [filename]

| Dimension    | Score | Problème clé    |
| ------------ | ----- | --------------- |
| Lisibilité   | X/10  | [une phrase]    |
| Voix         | X/10  | [une phrase]    |
| Complétude   | X/10  | [une phrase]    |
| Précision    | X/10  | [une phrase]    |
| **Total**    | X/40  |                 |

### Corrections prioritaires

1. [Priorité 1 combinée des deux rapports]
2. [Priorité 2 combinée]
3. [Priorité 3 combinée]
4. [Priorité 4 combinée]
5. [Priorité 5 combinée]
6. ...

Puis demander à l'utilisateur à l'aide de AskUserQuestion :

• Améliorer : Apporter des améliorations basées sur les résultats, puis réévaluer
• Compléter et terminer : Corriger tous les problèmes restants et quitter (pas de réévaluation)
• Terminé : Quitter la boucle sans apporter de modifications

Étape 3 : Triage (avant amélioration)

Avant de lancer l'agent d'amélioration, examiner les problèmes en attente avec l'utilisateur. Marquer les problèmes de complétude qui nécessitent l'ajout de nouvelles sections comme wont-fix - ce sont des expansions de documentation, pas des corrections d'examen.

Selon les directives dans AGENTS.md :

« Faire ce qui a été demandé ; ni plus, ni moins. » « Ne pas ajouter de fonctionnalités, refactoriser du code ou apporter des « améliorations » au-delà de ce qui a été demandé. »

La compétence d'examen améliore le contenu existant. L'ajout de nouvelles sections est une tâche séparée.

Étape 4 : Améliorer

Lancer un agent d'amélioration unique ciblant uniquement les problèmes en attente :

Task(subagent_type="general-purpose", model="opus", prompt="Improve documentation...")

Invite de l'agent d'amélioration

Améliorer la documentation en fonction des problèmes spécifiques suivis : $ARGUMENTS

Corriger UNIQUEMENT ces problèmes en attente :

| ID | Problème | Type | Notes |
|----|----------|------|-------|
[coller les problèmes en attente du fichier d'état]

Instructions :
1. Lire `../shared/writing-guide.md` et `../shared/docs-guide.md` relatifs au répertoire de cette compétence
2. Lire $ARGUMENTS

3. Pour chaque correction de précision :
   - Lire le fichier source référencé dans les notes
   - Vérifier l'API/comportement correct à partir de la source
   - Appliquer la correction en fonction de ce que le code source montre réellement

5. Appliquer les corrections de style

6. Exécuter prettier : yarn prettier --write $ARGUMENTS

NE PAS :
- Ajouter de nouvelles sections
- Étendre le document
- Corriger les problèmes qui ne figurent pas dans la liste ci-dessus

Retourner un résumé :

MODIFICATIONS APPORTÉES :

| ID | Correction appliquée | Vérification |
|----|----------------------|--------------|
| X | [description] | [fichier source:ligne vérifié] |
| Y | [description] | n/a |

Après amélioration, mettre à jour le fichier d'état pour marquer les problèmes comme fixed.

Étape 4b : Compléter et terminer (alternative à l'étape 4)

Si l'utilisateur sélectionne « Compléter et terminer », corriger tous les problèmes en attente restants sans réévaluer. Ceci est utile quand l'évaluation est satisfaisante et l'utilisateur souhaite appliquer les corrections et continuer.

Flux de travail :

1. Exécuter le triage (identique à l'étape 3) pour marquer les éléments hors du champ d'application comme wont-fix
2. Lancer l'agent d'amélioration (même invite qu'à l'étape 4)
3. Mettre à jour le fichier d'état pour marquer les problèmes comme fixed
4. Quitter la boucle - ne pas réévaluer

Ce chemin fait confiance à l'agent d'amélioration pour appliquer les corrections correctement et ignore le cycle de vérification. Utiliser quand :

• Les problèmes sont des corrections de style simples
• Le temps est limité et la réévaluation ne vaut pas la peine
• Les scores sont déjà acceptables et seul un polissage mineur reste

Étape 5 : Évaluation de vérification

Pour les cycles suivants, les agents d'évaluation vérifient les corrections ET découvrent les nouveaux problèmes :

Invite de l'agent de style (vérification)

Vérifier les corrections et évaluer la documentation : $ARGUMENTS

Lire d'abord le fichier d'état : [chemin du fichier d'état]

Puis lire les guides partagés relatifs au répertoire de cette compétence et le document cible :
1. `../shared/writing-guide.md`
2. `../shared/docs-guide.md`
3. $ARGUMENTS

Votre travail :
1. VÉRIFIER les corrections marquées comme « fixed » dans le fichier d'état - confirmer qu'elles ont réellement été appliquées
2. Noter les dimensions de style (NE PAS re-signaler les problèmes wont-fix)
3. Signaler uniquement les NOUVEAUX problèmes qui ne figurent pas déjà dans le fichier d'état

VÉRIFIER CES CORRECTIONS :
[coller les problèmes de style fixed du fichier d'état]

Retourner dans ce format :

RAPPORT DE VÉRIFICATION :

| ID | Statut | Notes |
|----|--------|-------|
| X | verified-fixed / not-fixed | [ce que vous avez trouvé] |

SCORES DE STYLE :
LISIBILITÉ : [score]/10
VOIX : [score]/10

NOUVEAUX PROBLÈMES (non signalés dans le fichier d'état) :
- [problème] ou « Aucun trouvé »

Invite de l'agent de contenu (vérification)

Vérifier les corrections et évaluer le contenu de la documentation : $ARGUMENTS

Lire d'abord le fichier d'état : [chemin du fichier d'état]

Puis lire $ARGUMENTS et vérifier les affirmations par rapport au code source dans packages/tldraw/.

Votre travail :
1. VÉRIFIER les corrections de précision marquées comme « fixed » dans le fichier d'état
2. Noter les dimensions de contenu (NE PAS re-signaler les problèmes wont-fix)
3. Signaler uniquement les NOUVEAUX problèmes de précision qui ne figurent pas déjà dans le fichier d'état

VÉRIFIER CES CORRECTIONS :
[coller les problèmes de précision fixed du fichier d'état]

Retourner dans ce format :

RAPPORT DE VÉRIFICATION :

| ID | Statut | Notes |
|----|--------|-------|
| X | verified-fixed / not-fixed | [ce que vous avez trouvé dans la doc ET la source] |

SCORES DE CONTENU :
COMPLÉTUDE : [score]/10 (noter le contenu existant uniquement, ignorer les éléments wont-fix)
PRÉCISION : [score]/10

NOUVEAUX PROBLÈMES DE PRÉCISION (non signalés dans le fichier d'état) :
- [problème avec fichier source:ligne] ou « Aucun trouvé »

Après vérification, mettre à jour le fichier d'état avec les nouveaux statuts et tout nouveau problème.

Étape 6 : Boucle

Continuer la boucle jusqu'à :

• L'utilisateur choisit « Terminé » (quitter sans modifications)
• L'utilisateur choisit « Compléter et terminer » (appliquer les corrections, puis quitter)
• Les scores atteignent des niveaux acceptables (32/40 ou plus)
• Tous les problèmes sont verified-fixed ou wont-fix

Remarques

• Le fichier d'état empêche de redécouvrir les mêmes problèmes au fil des cycles
• Les agents d'évaluation vérifient les corrections précédentes avant de noter
• wont-fix convient aux problèmes de complétude nécessitant de nouvelles sections
• La vérification de précision est critique : L'agent d'amélioration doit lire le code source réel avant d'appliquer une correction de précision
• Les évaluations de style et de contenu s'exécutent toujours en parallèle pour des raisons d'efficacité