109 lines
6.4 KiB
Markdown
109 lines
6.4 KiB
Markdown
<!-- file: docs/rules/PROMPT_STRUCTURE.md -->
|
|
<!-- version: 5 -->
|
|
|
|
# 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 dernière prerelease = validation finale + documentation + nettoyage/archivage + prompt de la release suivante ;
|
|
- une `fix` corrige l'étape réellement livrée sans réécrire l'historique.
|
|
|
|
## 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.
|
|
|
|
## 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.
|