# Structure des prompts KSP ## Portée Ce document définit le contrat normatif des prompts de reprise KSP, leur cycle de vie et les règles de dimensionnement des releases/sessions qu'ils préparent. Un prompt de démarrage est un **contrat opératoire autonome** : une nouvelle session ne doit pas dépendre d'une mémoire implicite pour retrouver les règles déjà acquises. ## Série, release concrète et session Une notation de série telle que `0.1.x` regroupe des fonctionnalités apparentées. Elle n'est pas une unité de session et n'a pas à être réalisable en une seule session. Le contrôle de charge s'applique d'abord à **la release concrète préparée** et à ses prereleases. Une release concrète doit être planifiée pour être ouverte et clôturée dans une seule session de chat ; si cette clôture paraît incertaine, elle est scindée avant l'implémentation lourde. ## Cycle d'une release concrète Sauf raison explicitement documentée : - `pre.001` = lectures obligatoires + audit interne/externe + brainstorming + sizing + planification ; - les prereleases intermédiaires = tranches bornées de développement/validation ; - la fermeture réserve des prereleases distinctes pour le gate technique/live, la réconciliation documentaire puis la préparation de publication ; - la dernière prerelease avant `rel.NNN` est une tranche de publication minimale, distincte de la réconciliation documentaire et des smokes ; - une `fix` corrige uniquement la responsabilité de la tranche à laquelle il est rattaché et ne sert pas à absorber un autre couloir de fermeture. ## Séparation obligatoire des dernières prereleases La queue de fermeture d'une release est structurée de manière à empêcher qu'un correctif de dernière minute mélange tests réseau, documentation durable et préparation de publication. Lorsqu'un smoke final ou un autre gate live est pertinent, les trois dernières responsabilités sont ordonnées ainsi : ```text pre.N-2 gate technique/live : smoke(s), graphes ou vérifications finales directement liées au runtime pre.N-1 réconciliation documentaire : plan, validation, README, USAGE et autres références durables concernées pre.N préparation de publication : prompt suivant + CHANGELOG + ROADMAP uniquement rel.001 mécanique de publication stable ``` Les numéros `N-2`, `N-1` et `N` sont relatifs : l'insertion d'une tranche ou d'une correction décale la numérotation réelle sans affaiblir cette séparation. Si aucun smoke/gate live final n'existe, le couloir `pre.N-2` est omis ; les deux dernières prereleases restent néanmoins séparées entre réconciliation documentaire et préparation de publication. La dernière prerelease ne modifie fonctionnellement que : ```text prompt de démarrage de la release suivante CHANGELOG.md ROADMAP.md ``` Les fichiers mécaniques imposés par le workflow restent autorisés : `Cargo.toml` pour la version d'une prerelease non-fix et `deltas//pre.NNN.md` pour sa traçabilité. Aucun README, USAGE, plan, validation, code, test, schema, config ou règle normative ne doit être introduit ou corrigé dans cette dernière tranche. La prerelease documentaire immédiatement précédente possède la réconciliation finale des documents durables de la release : README/USAGE, plan, validation, architecture/référence concernée et cohérence documentaire globale. Elle ne finalise ni `CHANGELOG.md`, ni `ROADMAP.md`, ni le prompt de la release suivante. Le gate technique/live, lorsqu'il existe, précède cette réconciliation documentaire. Les smokes et leurs corrections restent donc isolés avant que les documents finaux soient figés. Un `fix` reste local à son couloir. Si un défaut d'une responsabilité antérieure est découvert après avoir avancé, il ne doit pas être glissé dans le `fix` de la tranche courante : une nouvelle tranche dédiée à la responsabilité concernée est ouverte, puis les couloirs de fermeture postérieurs sont rejoués si nécessaire. La livraison `rel.NNN` ne sert jamais à absorber un correctif fonctionnel ou documentaire qui aurait dû être traité en prerelease. ## Dimensionnement Lors de `pre.001`, une prerelease intermédiaire estimée à plus d'environ **15 à 20 minutes de travail effectif** est scindée. Cette durée est un budget de planification, jamais une promesse temporelle. La trajectoire initiale est **souple** : elle indique un nombre prévisionnel de prereleases, leur objectif et leur ordre, mais autorise l'insertion de tranches/fixes lorsqu'un audit ou une validation révèle un besoin réel. La fermeture ne doit jamais être forcée pour respecter un numéro prévu. La prévision `pre.001` réserve explicitement les couloirs de fermeture applicables : gate technique/live éventuel, réconciliation documentaire, puis préparation de publication minimale. Leur numérotation peut dériver, mais leur ordre et leur séparation de responsabilités restent normatifs. ## Structure obligatoire d'un prompt de démarrage Un prompt de nouvelle session contient explicitement, dans un ordre facile à retrouver : 1. identité de la release et base exacte requise ; 2. mission et résultat attendu ; 3. **sources de vérité internes obligatoires et ordre de lecture** ; 4. sources externes normatives à réauditer lorsque la fraîcheur importe ; 5. état validé à préserver, y compris règles de dépendances et frontières ; 6. décisions acquises et questions réellement ouvertes ; 7. objectifs/livrables et hors périmètre ; 8. contraintes sécurité/API/architecture spécifiques ; 9. **première mission `pre.001` détaillée et critères de sortie de ce gate** ; 10. **prévision souple initiale des prereleases**, visible et détaillée ; 11. règles de versionnement, deltas, commits et tags ; 12. procédure d'application/validation opérateur ; 13. validations Rust/frontend/Tauri/réseau pertinentes ; 14. critères de clôture de la release ; 15. release/session suivante envisagée ; 16. **instruction d'ouverture** indiquant ce que la prochaine session doit faire en premier et ce qu'elle ne doit pas commencer avant le gate. ## Sources de vérité et reprise - Le prompt ordonne explicitement la lecture de `RULES.md`, `docs/000-README.md`, règles spécialisées, architecture, plan/validation de la release précédente et sources métier pertinentes. - Lorsqu'une archive/base opérateur est fournie, elle est déclarée autoritaire par rapport aux souvenirs, snippets ou artefacts anciens. - Le prompt ne recopie pas toutes les règles, mais rappelle les règles qui conditionnent directement la session et exige la lecture des fichiers normatifs. - Les décisions historiques ne sont pas réinventées lors de la nouvelle session ; une divergence avec la base réelle déclenche un audit, pas une supposition. ## Force opératoire du `pre.001` Le prompt doit rendre impossible une interprétation « commencer à coder immédiatement ». La première tranche exige au minimum : ```text lecture des sources internes obligatoires inventaire de l'état réel de la base récupération des dépendances/versions actuelles si concernées comparaison avec les références historiques utiles brainstorming des risques/frontières sizing de la release et de chaque tranche prévision souple recalibrée liste des validations/gates ``` L'implémentation fonctionnelle lourde commence seulement lorsque ce gate est cohérent. Les corrections triviales nécessaires pour rendre l'audit lui-même exécutable restent autorisées. ## Validation Rust obligatoire dans les prompts Toute release susceptible de modifier du Rust rappelle explicitement la séquence KSP : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets ``` Pendant le développement, les tests ciblés suivent ces contrôles. La fermeture d'une prerelease technique/release inclut `cargo test --workspace` et les `cargo tree` pertinents lorsque le graphe de dépendances a changé ou constitue un gate de la tranche. Un prompt interdit de déclarer réussie une commande qui n'a pas réellement été exécutée. Il rappelle que `rustfmt` et Clippy ne remplacent pas l'audit structurel KSP. ## Dépendances et fraîcheur Lorsqu'une tranche ajoute, met à jour ou dépend fortement d'une bibliothèque externe : - vérifier la version stable réellement courante au début de la tranche ; - préférer les sources primaires de la crate/projet ; - vérifier les features réellement nécessaires et les contraintes de versions transitives ; - documenter les doublons transitifs acceptés plutôt que forcer artificiellement une unification incompatible ; - ne pas conserver dans un prompt une version historique comme si elle était nécessairement toujours actuelle. ## Règles de rédaction - Le prompt doit être autoportant sans devenir une copie intégrale des règles. - Les titres `Première mission`, `Prévision souple`, `Validation` et `Instruction d'ouverture` doivent être immédiatement repérables. - Une règle normative appartient à `docs/rules/`, une décision durable à `docs/architecture/`, une idée non décidée à `docs/IDEAS.md`. - Le prompt signale les questions ouvertes au lieu de les résoudre arbitrairement. - Une release surdimensionnée est redécoupée avant ouverture de son développement lourd. - Le prompt conserve les conventions KSP de delta minimal, version de fichiers, Cargo version technique, commits et tags stables.