# Pi Auto-Improve — Design **Date :** 2026-05-10 **Statut :** Validé ## Résumé Système d'auto-amélioration pour Pi composé d'un skill (logique métier) et d'une extension légère (intégration Pi). L'utilisateur donne du feedback manuel (CLI ou boutons Telegram 👍/👎). Sur feedback négatif, Pi analyse l'échec, propose une leçon à valider. Les leçons sont stockées en JSON structuré, avec des règles globales toujours chargées au démarrage et des leçons domaine/projet consultées à la demande. ## Approche retenue Skill + Extension légère (Approche C) : - **Skill** = logique métier (analyse, génération de leçons, consolidation) - **Extension** = intégration Pi (commandes, hooks, Telegram, chargement contexte) ## Architecture ``` ~/Projects/pi-self-improve/ ├── README.md ├── docs/features/ # Design docs ├── skill/ │ └── auto-improve/ │ └── SKILL.md # Logique d'analyse et leçons ├── extension/ │ └── auto-improve.ts # Commandes, hooks, Telegram ├── data/ │ ├── feedback.jsonl # Historique brut des feedbacks │ ├── lessons/ │ │ ├── global.json # Leçons globales │ │ ├── domain-debug.json │ │ ├── domain-refactoring.json │ │ ├── domain-feature.json │ │ ├── domain-review.json │ │ └── domain-general.json │ └── projects/ │ └── .json # Leçons spécifiques par projet └── scripts/ └── install.sh # Installation dans ~/.pi/agent/ ``` ## Format de stockage ### feedback.jsonl Un JSON par ligne, append-only. ```json { "id": "abc123", "timestamp": "2026-05-10T14:30:00Z", "type": "positive | negative", "source": "cli | telegram", "session": "sess-456", "project": "/var/home/ajoye/Projects/my-app", "domain": "refactoring", "context": "Refactor du module auth", "user_comment": "Trop de changements d'un coup" } ``` Champs : - `id` — identifiant unique (timestamp-based) - `timestamp` — ISO 8601 - `type` — `positive` ou `negative` - `source` — `cli` (commande `/good`/`/bad`) ou `telegram` (bouton) - `session` — ID de la session Pi - `project` — chemin du projet (cwd au moment du feedback) - `domain` — domaine détecté ou `general` par défaut - `context` — résumé court de la tâche en cours - `user_comment` — texte libre optionnel ### lessons/*.json et projects/*.json Même structure, scope différent. ```json { "project": "global", "updated": "2026-05-10T14:35:00Z", "lessons": [ { "id": "l-001", "created": "2026-05-10T14:35:00Z", "domain": "refactoring", "rule": "Toujours découper les refactors larges en petites étapes incrémentales, une fonction ou un fichier à la fois", "rationale": "L'utilisateur préfère voir chaque étape validée avant de continuer", "source_feedback": ["abc123"], "positive_examples": 2, "violations": 0, "active": true } ] } ``` Champs : - `id` — identifiant unique de la leçon - `created` — date de création - `domain` — `debug`, `refactoring`, `feature`, `review`, `general` - `rule` — la leçon en langage naturel, concise et actionnable - `rationale` — pourquoi cette règle existe - `source_feedback` — IDs des feedbacks ayant généré cette leçon - `positive_examples` — compteur de fois où la règle a été suivie avec succès - `violations` — compteur de fois où la règle a été enfreinte - `active` — `false` = désactivée sans suppression Hash projet : hash court (6-8 chars) du chemin absolu du projet. ## Extension (auto-improve.ts) ### Commandes | Commande | Description | |----------|-------------| | `/good [commentaire]` | Enregistre un feedback positif | | `/bad [commentaire]` | Feedback négatif + déclenche l'analyse | | `/lessons [scope]` | Affiche les leçons (global, domain, project) | | `/lesson-add ` | Ajout manuel d'une leçon | | `/lesson-remove ` | Désactive une leçon | ### Hooks - **`on("session_start")`** — Charge `global.json` et l'injecte dans le contexte - **`on("tool_call", filter="bash")`** — Détecte le domaine courant basé sur les actions ### Intégration Telegram Après chaque réponse en mode Telegram, ajout de boutons cachés : ``` ``` Le feedback négatif via bouton déclenche le même flux que `/bad`. ### Chargement au démarrage Le fichier `global.json` est lu, formaté en Markdown, injecté dans le contexte : ```markdown ## Leçons apprises (auto-improve) - [refactoring] Toujours découper les refactors en petites étapes incrémentales - [debug] Commencer par reproduire le bug avant de proposer des fixes ``` ## Skill (auto-improve/SKILL.md) ### Frontmatter ```yaml --- name: auto-improve description: "Use when the user gives negative feedback (👎, /bad) or asks to analyze a failure. Handles failure analysis, lesson generation, and lesson consolidation." --- ``` ### Responsabilités 1. **Analyser l'échec** — Examiner la conversation récente, identifier la cause 2. **Formuler une leçon** — Règle concise, actionnable, en français 3. **Détecter le domaine** — `debug`, `refactoring`, `feature`, `review`, `general` 4. **Proposer à l'utilisateur** — Validation avant stockage 5. **Consolider** — Fusionner avec les leçons existantes si similaire ### Processus ``` Feedback négatif reçu → Relire les derniers échanges → Identifier la cause probable → Vérifier si une leçon similaire existe → Si oui : proposer une fusion → Si non : proposer une nouvelle leçon → Présenter à l'utilisateur : règle + justification → Si validé → écrire dans le JSON → Si refusé → ne rien stocker ``` ### Consultation à la demande `/lessons domain debug` ou `/lessons project` : - Lire le JSON correspondant - Filtrer `active: true` - Présenter en liste concise ## Chargement hybride - **Toujours chargé** : `global.json` → injecté au démarrage de chaque session - **À la demande** : leçons domaine et projet → consultées via `/lessons` ou par le skill quand c'est pertinent ## Domaines supportés | Domaine | Détection | |---------|-----------| | `debug` | Commandes de test, grep d'erreurs, lecture de stack traces | | `refactoring` | Modifications multiples de fichiers existants | | `feature` | Création de nouveaux fichiers, ajout de fonctionnalités | | `review` | Lecture de code sans modification | | `general` | Par défaut, quand aucun domaine clair | ## Décisions de design 1. **Pas d'auto-correction immédiate** — Sur feedback négatif, analyse + proposition de leçon uniquement. L'utilisateur valide. 2. **Feedback positif stocké aussi** — Sert pour les compteurs `positive_examples` et pour renforcer les leçons existantes. 3. **Leçons désactivables** — `active: false` plutôt que suppression, pour garder l'historique. 4. **Pas de ML** — Tout repose sur l'analyse par le LLM et la validation humaine. 5. **Hash court pour les projets** — Pas de chemins complets dans les noms de fichiers.