khadhroony-solana-project/docs/rules/PROMPT_STRUCTURE.md

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 :

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 :

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/<X.Y.Z>/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 :

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 :

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.