145 lines
9.4 KiB
Markdown
145 lines
9.4 KiB
Markdown
<!-- file: docs/rules/PROMPT_STRUCTURE.md -->
|
|
<!-- version: 6 -->
|
|
|
|
# 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/<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 :
|
|
|
|
```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.
|