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 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.