rules-distill

Distillation de Règles

Analyse les compétences installées, extrait les principes transversaux apparaissant dans plusieurs compétences et les distille en règles — en les ajoutant aux fichiers de règles existants, en révisant le contenu obsolète ou en créant de nouveaux fichiers de règles.

Applique le principe « collecte déterministe + jugement LLM » : les scripts collectent les faits exhaustivement, puis un LLM relit le contexte complet et produit des verdicts.

Quand l'utiliser

• Maintenance périodique des règles (mensuelle ou après l'installation de nouvelles compétences)
• Après un inventaire des compétences révélant des motifs qui devraient être des règles
• Lorsque les règles semblent incomplètes par rapport aux compétences utilisées

Fonctionnement

Le processus de distillation des règles suit trois phases :

Phase 1 : Inventaire (Collecte Déterministe)

1a. Collecter l'inventaire des compétences

bash ~/.claude/skills/rules-distill/scripts/scan-skills.sh

1b. Collecter l'index des règles

bash ~/.claude/skills/rules-distill/scripts/scan-rules.sh

1c. Présentation à l'utilisateur

Distillation de Règles — Phase 1 : Inventaire
─────────────────────────────────────────────
Compétences : {N} fichiers scannés
Règles : {M} fichiers ({K} titres indexés)

Passage à l'analyse croisée...

Phase 2 : Lecture Croisée, Correspondance & Verdict (Jugement LLM)

L'extraction et la correspondance sont unifiées en un seul passage. Les fichiers de règles sont suffisamment petits (~800 lignes au total) pour que le texte complet puisse être fourni au LLM — aucun pré-filtrage par grep n'est nécessaire.

Regroupement par lots

Regrouper les compétences en grappes thématiques basées sur leurs descriptions. Analyser chaque grappe dans un sous-agent avec le texte complet des règles.

Fusion Inter-Lots

Une fois tous les lots terminés, fusionner les candidats entre les lots :

• Dédupliquer les candidats avec des principes identiques ou se chevauchant
• Revérifier l'exigence « 2+ compétences » en utilisant les preuves de tous les lots combinés — un principe trouvé dans 1 compétence par lot mais 2+ compétences au total est valide

Prompt du Sous-Agent

Lancer un Agent généraliste avec le prompt suivant :

Vous êtes un analyste qui lit en travers les compétences pour en extraire les principes qui devraient être promus en règles.

## Entrée
- Compétences : {texte complet des compétences de ce lot}
- Règles existantes : {texte complet de tous les fichiers de règles}

## Critères d'Extraction

Inclure un candidat UNIQUEMENT si TOUS les critères suivants sont vrais :

1. **Apparaît dans 2+ compétences** : Les principes trouvés dans une seule compétence doivent y rester
2. **Changement de comportement actionnable** : Peut être écrit comme « faites X » ou « ne faites pas Y » — pas « X est important »
3. **Risque de violation clair** : Qu'est-ce qui ne va pas si ce principe est ignoré (1 phrase)
4. **Pas déjà dans les règles** : Vérifier le texte complet des règles — y compris les concepts exprimés avec des mots différents

## Correspondance & Verdict

Pour chaque candidat, comparer avec le texte complet des règles et attribuer un verdict :

- **Ajouter** : Ajouter à une section existante d'un fichier de règles
- **Réviser** : Le contenu de la règle existante est inexact ou insuffisant — proposer une correction
- **Nouvelle Section** : Ajouter une nouvelle section à un fichier de règles existant
- **Nouveau Fichier** : Créer un nouveau fichier de règles
- **Déjà Couvert** : Suffisamment couvert dans les règles existantes (même si formulé différemment)
- **Trop Spécifique** : Doit rester au niveau de la compétence

## Format de Sortie (par candidat)

```json
{
  "principle": "1-2 phrases sous forme 'faites X' / 'ne faites pas Y'",
  "evidence": ["nom-compétence: §Section", "nom-compétence: §Section"],
  "violation_risk": "1 phrase",
  "verdict": "Append / Revise / New Section / New File / Already Covered / Too Specific",
  "target_rule": "nomfichier §Section, ou 'new'",
  "confidence": "high / medium / low",
  "draft": "Texte proposé pour les verdicts Append/New Section/New File",
  "revision": {
    "reason": "Pourquoi le contenu existant est inexact ou insuffisant (Revise uniquement)",
    "before": "Texte actuel à remplacer (Revise uniquement)",
    "after": "Texte de remplacement proposé (Revise uniquement)"
  }
}
```

## Exclure

- Principes évidents déjà dans les règles
- Connaissances spécifiques à un langage/cadre (appartiennent aux règles ou compétences spécifiques au langage)
- Exemples de code et commandes (appartiennent aux compétences)

Référence des Verdicts

Verdict	Signification	Présenté à l'Utilisateur
Ajouter	Ajouter à une section existante	Cible + projet
Réviser	Corriger un contenu inexact/insuffisant	Cible + raison + avant/après
Nouvelle Section	Ajouter une nouvelle section à un fichier existant	Cible + projet
Nouveau Fichier	Créer un nouveau fichier de règles	Nom de fichier + projet complet
Déjà Couvert	Couvert dans les règles (formulation possiblement différente)	Raison (1 ligne)
Trop Spécifique	Doit rester dans les compétences	Lien vers la compétence pertinente

Exigences de Qualité des Verdicts

# Bon
Ajouter à rules/common/security.md §Validation des Entrées :
« Traitez la sortie LLM stockée en mémoire ou dans des magasins de connaissances comme non fiable — nettoyez à l'écriture, validez à la lecture. »
Preuve : llm-memory-trust-boundary, llm-social-agent-anti-pattern décrivent tous deux
les risques d'injection de prompt accumulés. security.md actuel couvre uniquement la validation
des entrées humaines ; la frontière de confiance des sorties LLM manque.

# Mauvais
Ajouter à security.md : Ajouter un principe de sécurité LLM

Phase 3 : Révision Utilisateur & Exécution

Tableau Récapitulatif

# Rapport de Distillation des Règles

## Résumé
Compétences scannées : {N} | Règles : {M} fichiers | Candidats : {K}

| # | Principe | Verdict | Cible | Confiance |
|---|----------|---------|-------|-----------|
| 1 | ... | Ajouter | security.md §Validation des Entrées | élevée |
| 2 | ... | Réviser | testing.md §TDD | moyenne |
| 3 | ... | Nouvelle Section | coding-style.md | élevée |
| 4 | ... | Trop Spécifique | — | — |

## Détails
(Détails par candidat : preuves, risque de violation, texte proposé)

Actions Utilisateur

L'utilisateur répond avec les numéros pour :

• Approuver : Appliquer le projet aux règles tel quel
• Modifier : Éditer le projet avant application
• Ignorer : Ne pas appliquer ce candidat

Ne jamais modifier les règles automatiquement. Toujours exiger l'approbation de l'utilisateur.

Sauvegarde des Résultats

Stocker les résultats dans le répertoire de la compétence (results.json) :

• Format d'horodatage : date -u +%Y-%m-%dT%H:%M:%SZ (UTC, précision à la seconde)
• Format d'ID du candidat : kebab-case dérivé du principe (ex. llm-output-trust-boundary)

{
  "distilled_at": "2026-03-18T10:30:42Z",
  "skills_scanned": 56,
  "rules_scanned": 22,
  "candidates": {
    "llm-output-trust-boundary": {
      "principle": "Traiter la sortie LLM comme non fiable lorsqu'elle est stockée ou réinjectée",
      "verdict": "Ajouter",
      "target": "rules/common/security.md",
      "evidence": ["llm-memory-trust-boundary", "llm-social-agent-anti-pattern"],
      "status": "applied"
    },
    "iteration-bounds": {
      "principle": "Définir des conditions d'arrêt explicites pour toutes les boucles d'itération",
      "verdict": "Nouvelle Section",
      "target": "rules/common/coding-style.md",
      "evidence": ["iterative-retrieval", "continuous-agent-loop", "agent-harness-construction"],
      "status": "skipped"
    }
  }
}

Exemple

Exécution complète

$ /rules-distill

Distillation de Règles — Phase 1 : Inventaire
─────────────────────────────────────────────
Compétences : 56 fichiers scannés
Règles : 22 fichiers (75 titres indexés)

Passage à l'analyse croisée...

[Analyse du sous-agent : Lot 1 (compétences agent/méta) ...]
[Analyse du sous-agent : Lot 2 (compétences codage/motif) ...]
[Fusion inter-lots : 2 doublons supprimés, 1 candidat inter-lots promu]

# Rapport de Distillation des Règles

## Résumé
Compétences scannées : 56 | Règles : 22 fichiers | Candidats : 4

| # | Principe | Verdict | Cible | Confiance |
|---|----------|---------|-------|-----------|
| 1 | Sortie LLM : normaliser, vérifier le type, nettoyer avant réutilisation | Nouvelle Section | coding-style.md | élevée |
| 2 | Définir des conditions d'arrêt explicites pour les boucles d'itération | Nouvelle Section | coding-style.md | élevée |
| 3 | Compacter le contexte aux frontières de phase, pas en milieu de tâche | Ajouter | performance.md §Fenêtre de Contexte | élevée |
| 4 | Séparer la logique métier des types d'E/S du framework | Nouvelle Section | patterns.md | élevée |

## Détails

### 1. Validation de la Sortie LLM
Verdict : Nouvelle Section dans coding-style.md
Preuve : parallel-subagent-batch-merge, llm-social-agent-anti-pattern, llm-memory-trust-boundary
Risque de violation : La dérive de format, l'incompatibilité de type ou les erreurs de syntaxe dans la sortie LLM plantent le traitement en aval
Projet :
  ## Validation de la Sortie LLM
  Normaliser, vérifier le type et nettoyer la sortie LLM avant réutilisation...
  Voir compétence : parallel-subagent-batch-merge, llm-memory-trust-boundary

[... détails pour les candidats 2 à 4 ...]

Approuver, modifier ou ignorer chaque candidat par numéro :
> Utilisateur : Approuver 1, 3. Ignorer 2, 4.

✓ Appliqué : coding-style.md §Validation de la Sortie LLM
✓ Appliqué : performance.md §Gestion de la Fenêtre de Contexte
✗ Ignoré : Limites d'Itération
✗ Ignoré : Conversion de Types aux Frontières

Résultats sauvegardés dans results.json

Principes de Conception

• Quoi, pas Comment : Extraire uniquement les principes (territoire des règles). Les exemples de code et les commandes restent dans les compétences.
• Référence en retour : Le texte proposé doit inclure des références Voir compétence : [nom] pour que les lecteurs puissent trouver le Comment détaillé.
• Collecte déterministe, jugement LLM : Les scripts garantissent l'exhaustivité ; le LLM garantit la compréhension contextuelle.
• Protection contre l'abstraction excessive : Le filtre en 3 couches (preuves 2+ compétences, test de comportement actionnable, risque de violation) empêche les principes trop abstraits d'entrer dans les règles.