v0.0.3-pre.001

docs/rules/PROMPT_STRUCTURE.md

@@ -0,0 +1,203 @@
+<!-- file: docs/rules/PROMPT_STRUCTURE.md -->
+<!-- version: 2 -->
+
+# 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 sessions/prereleases qu'ils préparent.
+
+Les prompts eux-mêmes sont conservés sous `prompts/`.
+
+## Objectif
+
+Un prompt doit permettre de reprendre le travail sans reconstituer manuellement :
+
+- la mission de la phase ;
+- la base Git/version ;
+- l'état validé à préserver ;
+- les règles applicables ;
+- l'architecture déjà décidée ;
+- les questions encore ouvertes ;
+- les sources externes normatives lorsqu'elles existent ;
+- le plan souple ;
+- le mode de livraison ;
+- les validations et critères de sortie.
+
+Le prompt ne remplace jamais les sources de vérité du dépôt.
+
+## Cycle de vie
+
+Un prompt de prochaine grande phase est créé dès que sa direction devient suffisamment claire.
+
+Il passe par trois états conceptuels :
+
+1. **Brouillon** — créé tôt et volontairement incomplet ;
+2. **Quasi-final** — mis à jour lorsque les frontières, crates, dépendances et objectifs sont suffisamment stabilisés ;
+3. **Final** — vérifié pendant la phase documentaire de clôture et prêt à être utilisé comme point de départ de la session/version suivante.
+
+Le prompt de la phase suivante doit être maintenu pendant la phase courante lorsque de nouvelles décisions changent matériellement son futur démarrage.
+
+## Première et dernière prerelease d'une version
+
+Sauf raison explicitement documentée :
+
+- la première prerelease (`pre.001`) est consacrée au brainstorming, à l'audit lorsque nécessaire, à la planification, aux décisions de périmètre et au découpage souple des prereleases suivantes ;
+- la dernière prerelease est consacrée à la validation finale, à la documentation, au nettoyage/archivage nécessaire, à la synchronisation des documents de release et à la finalisation du prompt de la session/version suivante.
+
+Le développement fonctionnel significatif ne doit pas précéder le cadrage suffisant de `pre.001`.
+
+## Dimensionnement des prereleases
+
+Pendant l'élaboration du plan de `pre.001`, les prereleases de travail situées après `pre.001` et avant la prerelease finale de clôture doivent être conçues comme des tranches bornées.
+
+Lors de la planification, une tranche dont la charge estimée paraît dépasser approximativement **15 à 20 minutes de travail effectif de session** doit être scindée en plusieurs prereleases ou sous-objectifs livrables séparément.
+
+Cette durée est un budget de planification, pas une promesse de temps d'exécution. Elle sert à empêcher les tranches trop larges, difficiles à valider ou à corriger.
+
+Si la complexité réelle découverte en cours de travail dépasse l'estimation, la tranche doit être redécoupée plutôt que surchargée.
+
+## Dimensionnement d'une session ou d'une version
+
+Avant de finaliser le prompt de la session suivante, il faut évaluer la charge totale produite par le plan prévu.
+
+Si un prompt risque de générer trop de prereleases, trop de fichiers, trop de décisions ou un contexte trop lourd pour une seule session de qualité, le périmètre doit être découpé :
+
+- en plusieurs sessions conservant éventuellement la même série/version lorsque la continuité fonctionnelle le justifie ;
+- et/ou en plusieurs versions lorsque la séparation correspond à une frontière fonctionnelle plus propre.
+
+Exemple : si une version prévue pour introduire decoder + executor devient manifestement trop lourde après planification, la continuité du roadmap est conservée mais le travail peut être réparti sur plusieurs sessions ou versions.
+
+La qualité du contexte, la testabilité et la cohérence architecturale priment sur le maintien artificiel d'un découpage de versions imaginé plus tôt.
+
+## Structure recommandée d'un prompt
+
+### 1. Identité de la phase
+
+Indiquer :
+
+- version ou série visée ;
+- titre court ;
+- nature de la session : brainstorming, planification, développement, audit, validation, clôture, etc.
+
+### 2. Mission
+
+Décrire l'état concret à atteindre pendant la phase.
+
+La mission ne doit pas être une simple liste de fichiers à modifier.
+
+### 3. Base requise
+
+Indiquer :
+
+- version/tag/commit de départ ;
+- état attendu du workspace ;
+- fichiers/documents fondamentaux déjà présents.
+
+### 4. État validé à préserver
+
+Lister les éléments déjà validés qui ne doivent pas régresser pendant la nouvelle phase, par exemple :
+
+- APIs déjà stabilisées ;
+- comportements fonctionnels validés ;
+- tests/scénarios connus comme passants ;
+- décisions gelées ou fortement contraintes ;
+- problèmes explicitement reportés qui ne doivent pas être rouverts sans raison.
+
+Cette section est distincte de la simple base Git/version.
+
+### 5. Sources de vérité internes à relire
+
+Lister explicitement les documents nécessaires, en priorité :
+
+- `RULES.md` et règles spécialisées pertinentes ;
+- `ROADMAP.md` ;
+- plan de version actif ;
+- architecture concernée ;
+- `docs/IDEAS.md` lorsqu'une question ouverte est pertinente ;
+- dernier delta/release utile.
+
+Le prompt doit renvoyer aux sources de vérité au lieu de les recopier intégralement.
+
+### 6. Sources externes normatives
+
+Lorsqu'une phase concerne un protocole, programme, standard ou API externe, lister les sources qui font autorité :
+
+- dépôt upstream officiel ;
+- documentation officielle ;
+- IDL/schema officiel ;
+- Program ID ;
+- format wire ;
+- spécification normative ;
+- autre source externe explicitement retenue.
+
+Une copie historique locale ne doit pas être traitée comme source de vérité actuelle lorsque la phase exige une vérification upstream.
+
+### 7. Décisions acquises
+
+Résumer uniquement les décisions indispensables pour éviter une mauvaise direction au démarrage.
+
+### 8. Objectifs et livrables
+
+Lister les objectifs principaux et les artefacts attendus.
+
+### 9. Hors périmètre
+
+Indiquer ce qui ne doit explicitement pas être ouvert pendant la phase.
+
+### 10. Méthode de travail
+
+Rappeler la séquence KSP applicable :
+
+1. brainstorming ;
+2. planification ;
+3. développement lorsque la phase est fonctionnelle ;
+4. tests/validations ;
+5. documentation finale ;
+6. mise à jour/préparation du prompt suivant.
+
+Une phase fondatrice/documentaire adapte la partie développement à son objet.
+
+### 11. Versionnement et deltas
+
+Rappeler :
+
+- version Cargo attendue ;
+- format du delta ;
+- règle des fixes techniques/documentaires ;
+- politique de commits de la phase ;
+- règle de découpage des livraisons trop volumineuses.
+
+### 12. Contraintes techniques spécifiques
+
+Lister uniquement les contraintes importantes pour cette phase : dépendances, environnements, sécurité, API publique, stockage, transport, etc.
+
+### 13. Plan initial souple
+
+Pour un `pre.001`, fournir la prévision souple des prereleases ou étapes principales.
+
+Chaque tranche intermédiaire doit respecter le budget de complexité défini plus haut et être redécoupée si nécessaire.
+
+### 14. Validations attendues
+
+Indiquer les commandes/tests/audits pertinents et interdire de déclarer une validation non exécutée.
+
+### 15. Critères de sortie
+
+Décrire les conditions nécessaires pour considérer la phase terminée.
+
+### 16. Préparation de la suite
+
+Indiquer quel document/prompt doit être produit ou mis à jour avant la clôture.
+
+Avant finalisation de ce prompt suivant, appliquer obligatoirement le contrôle de dimensionnement de session/version.
+
+## Règles de rédaction
+
+- Le prompt est précis mais évite de dupliquer plusieurs pages déjà présentes dans les documents canoniques.
+- Une règle normative appartient d'abord à `docs/rules/`, pas seulement au prompt.
+- Une décision architecturale durable appartient à `docs/architecture/`, pas seulement au prompt.
+- Une idée non décidée appartient à `docs/IDEAS.md`.
+- Le prompt doit signaler les questions ouvertes plutôt que les résoudre arbitrairement.
+- Les chemins et versions mentionnés doivent être cohérents avec le dépôt au moment de la finalisation.
+- Un prompt final ne doit pas préparer une session manifestement surdimensionnée.