jumibot/documento_fundacional

Document fondateur

Le document fondateur présente un projet, ou un produit d'une famille, de manière formelle et compacte : quel besoin il répond, pourquoi il mérite d'être développé, ce qu'il est, dans quelles situations il apporte de la valeur, ce qui le soutient et ce qu'il doit démontrer. C'est la description de référence du projet.

Il se distingue du document de vision (compétence documento_vision) de trois manières :

• Sans histoire fil conducteur. Il n'y a pas de cas, de scènes ni de prologue. C'est une description ordonnée, comme un dossier.
• Plus formel. Chaque affirmation du domaine est accompagnée de sa référence, et on sépare toujours ce qui est publié, ce qui est un objectif de conception et ce qui est une hypothèse de calcul.
• Pour l'auteur et pour partager. Il sert à l'auteur (et à Claude lors de sessions futures) comme description compacte et sans distractions, et peut être remis tel quel à des collaborateurs, partenaires ou financeurs.

Les deux coexistent. La vision raconte le projet avec une histoire ; le fondateur le décrit. Si l'un change, l'autre est révisé.

Cette compétence indique ce que contient un fondateur et comment il s'écrit. Le générateur, les ressources et leur syntaxe, les thèmes, les outils et la vérification sont ceux communs de crear_documentos, qui se lit parallèlement à celle-ci.

Où le placer

Les documents fondateurs d'un projet se trouvent ensemble dans docs/specs/vision/ (méthodologie SF, « Structure documentaire commune ») : la vision, le fondateur et les infographies techniques dans infografias/.

• Du projet : docs/specs/vision/fundacional-<projet>.md et son .html.
• De chaque produit d'une famille, s'il en a un : fundacional-<produit>.md.

Le .md est la source. Le .html est généré et ne se modifie pas à la main. Si on part d'un PDF ou d'un HTML existant, on le convertit en .md et l'original est conservé à côté ou dans _respaldo/.

Modèle. Si le projet a déjà un fondateur qui applique bien ces règles, on le lit comme exemple lors de l'écriture ou de la révision d'un autre ; ce qui est propre à son domaine n'est pas copié.

Sections

Il y a un noyau que tout document fondateur possède et des sections optionnelles qui sont incluses lorsque le projet en a besoin. Elles sont numérotées dans l'ordre où elles apparaissent. Les annexes vont à la fin, avec l'étiquette « Annexe A · … ».

Ordre : d'abord expliquer, ensuite justifier. Le lecteur doit savoir ce qu'est le produit avant d'évaluer les arguments. Après l'ouverture (but, s'il existe, et prose de la raison de développer avec l'idée, la différence et la thèse), viennent les sections qui expliquent : le système ou la famille, le produit et son fonctionnement, les scénarios et les alternatives. Ensuite, celles qui justifient : le besoin documenté et le coût du problème, l'impact, le dimensionnement, les risques et « Ce qui doit être démontré ». Les cartes du besoin documenté peuvent aller dans leur propre section, après le produit, si l'ouverture résume déjà la thèse.

Page de garde sobre. Marque, nom et devise en police normale (une ou deux lignes). Rien d'autre, pour que l'en-tête soit discret : l'idée avec le but ouvre la première section comme accroche, la version et l'état vont en bas de page, et il n'y a pas de ligne de chiffres (compter des fiches ou des preuves est un inventaire, pas un argument ; si un chiffre argumente, il va dans le texte).

Avertissements de portée globale (ce qui dans le document est un objectif de conception et ce qui est validé, ou tout critère qui s'applique à l'ensemble du texte) : ils vont au début, en dehors de toute section. Ils s'écrivent comme une citation > entre le # Nom et la première ## ; le générateur les place avant les sections, sous forme d'encadré.

Noyau

1. Raison de développer. Commence par une prose initiale, avant les cartes et sans sous-titres :

   • l'idée avec le but, comme accroche ;
   • la différence par rapport aux alternatives existantes, dans un paragraphe, avec sa référence et une phrase par alternative ;
   • la thèse de développement : ce qui mérite d'être financé ou construit maintenant et à quelle condition cela aura de la valeur. Elle va en prose, pas dans un encadré, et est justifiée : sur quels faits du document elle s'appuie, avec son chiffre et sa référence, et ce qui reste à savoir, ce qui doit être mesuré par le pilote.

   Ensuite, deux ou trois cartes avec le besoin documenté (le problème mesuré, la capacité d'intervenir, la conséquence), chacune avec sa référence. Cette forme, une prose qui argumente puis des cartes justifiées, est le modèle de toutes les sections (voir « Règles de rédaction »).

2. Le produit. Ce qu'il est en quelques chiffres (capacité, autonomie, portée…), comment il fonctionne par sous-systèmes, son architecture, ses fonctions principales, comment il évolue (famille, plateforme, vérifier/reconfigurer/redéfinir) et ce qu'il ne fait pas.

3. Scénarios d'utilisation. Les situations dans lesquelles le produit peut apporter de la valeur, avec un code pour chacun (S1, S2…) pour les citer dans le reste du document. Dans chacun : quand il apporte de la valeur, limite de l'argument, quoi mesurer et la base documentaire. Les scénarios sont compatibles entre eux ; ils ne s'additionnent pas comme des populations indépendantes.

4. Preuves. D'abord, la méthode et la portée de la recherche. Ensuite, une carte par preuve : type (mesure, pilote, guide, étude…), ce qu'elle dit avec son chiffre, à quels scénarios elle affecte et une lecture pour le projet qui indique ce qu'elle soutient et ce qu'elle ne soutient pas.

5. Ce qui doit être démontré. Le passage du document au pilote : phases priorisées, chacune avec son circuit, son motif et sa condition pour avancer ; les validations nécessaires (technique, opérationnelle, économique) ; les décisions d'avancement (portes) ; la décision proposée et comment elle sera mesurée.

6. Sources et références. Toutes les sources avec un code par type (par exemple E pour preuves, F pour fiches techniques, P pour prix, D pour économie, C pour clinique, M pour documents du projet lui-même), leur provenance, leur lien et la date de révision.

Optionnelles

• But et valeurs (mission, vision et valeurs), au début, comme section propre ou comme cartes dans la première section. Pour les projets qui cherchent à aligner une équipe ou des collaborateurs.
• Coût du problème, lorsqu'il y a une dimension économique : cas documentés avec leur chiffre et leur « implication et portée », ce qui peut être évité et le modèle économique (une formule). Il va après la raison de développer.
• Dimensionnement du marché ou du territoire : ce que les sources permettent d'affirmer et ce qu'elles ne permettent pas, quelles données seraient nécessaires (dénominateur, exposition, économie), un scénario transparent (peut inclure un calculateur comme composant propre) et comment le convertir en une estimation défendable. Il va avant « Ce qui doit être démontré ».
• Annexe de comparaison avec une référence existante : une carte par dimension, avec deux colonnes (« référence · publié » et « projet · conception ») et l'apport de chaque approche. À la fin, les valeurs que la comparaison doit conserver et comment vérifier la valeur ajoutée.
• Annexe de fiches par élément (médicaments, matériaux, composants, clients types…) : une fiche par élément avec ses données et ses scénarios. Le générateur ajoute un moteur de recherche et un filtre par scénario.
• Impact : ce qui changerait si le produit fonctionne, toujours conditionné à ce que démontre le pilote. Une carte par dimension (économique, pour les personnes, pour le territoire ou l'environnement) avec « Ce qui peut changer » et son indicateur, mesurable avant et après. La prose initiale nomme la ligne de base qui existe déjà et ce qui reste à mesurer ; aucun chiffre d'économie n'est attribué au projet sans ce contraste. Les ODD, s'ils sont cités, le sont avec leur nom officiel et leur source. Il va après le coût du problème ou le besoin.
• Risques : ce qui peut échouer et comment les atténuer. Une carte par risque, avec sa classe comme étiquette (technique, opérationnel, économique, réglementaire), « Atténuation » et « Se vérifie dans », qui renvoie à une phase ou une porte de « Ce qui doit être démontré ». La prose initiale indique le risque principal et comment le plan le détecte tôt. Ce qui n'a pas encore été analysé (par exemple, l'adéquation réglementaire) est déclaré comme risque ouvert, avec ses sources lorsqu'elles existent. Il va juste avant « Ce qui doit être démontré ».
• Invitation à collaborer : quels profils sont recherchés, ce qui est offert et ce qui est attendu. Pour les documents qui sont partagés.

Lecture par couches. On communique d'abord le plus important, et chaque couche suivante approfondit : celui qui ne lit que la première section retient l'essentiel, et celui qui veut plus continue à lire. L'ordre est celui de l'importance, pas celui de la façon dont on est arrivé aux conclusions. Cela vaut pour tout le document et pour chaque section, qui ouvre avec sa conclusion (voir « Règles de rédaction ») et laisse le détail aux cartes, aux #### pliés et aux annexes.

Si le projet a besoin d'une section qui n'est pas ici, on la propose à l'auteur avant de l'écrire. Si elle est utile pour d'autres projets, c'est une amélioration de cette compétence, qui appartient à la SF : on ne l'ajoute pas dans le projet, on le dit en une ligne ; dans la SF elle-même, elle appartient au projet.

Règles de rédaction

• Seule la dernière décision. Le document décrit l'état actuel, sans historique.
• Trois classes d'affirmation, toujours séparées : faits publiés (avec référence), objectifs de conception du projet (ce qu'on veut qu'il fasse) et hypothèses de calcul (marquées comme illustratives). Un encadré de portée au début l'explique, et les étiquettes « publié » et « conception » le rappellent là où on les compare.
• Tout chiffre ou affirmation du domaine est vérifié par des sources avant d'être écrit, jamais de mémoire, et porte sa référence dans la même phrase. Pour chercher sur le web, demander la permission à l'auteur si elle n'a pas été donnée.
• Chaque preuve dit aussi ce qu'elle ne démontre pas. « Lecture pour le projet », « Limite de l'argument », « Implication et portée » : le document gagne en crédibilité lorsqu'il marque ses propres limites.
• Concis. Paragraphes de deux ou trois phrases, phrases d'environ 20 mots ou moins, sigles expliqués la première fois. Le noyau se lit d'une traite ; le détail long va dans les annexes.
• Sans fioritures. Rien sur le document lui-même (« Il faut mettre à jour ce document… », « Ce document ne contient pas… ») ni d'évidences : chaque phrase apporte quelque chose du projet.
• Chaque section commence par une prose qui argumente, comme la première : environ deux ou trois paragraphes, avant toute carte et sans sous-titres, avec la conclusion de la section, les faits qui la soutiennent avec leur chiffre et leur référence, et ce qui reste à savoir. Une phrase de présentation (« Six expériences permettent… ») ne suffit pas. La thèse ou la lecture d'ensemble va dans cette prose, pas dans un encadré. Les cartes viennent ensuite et apportent le détail consultable, sans répéter l'argument.
• Phrases complètes, pas de catalogue. Dans chaque section (###), on écrit avec des phrases avec verbe qui expliquent comment quelque chose fonctionne et pourquoi, pas d'énumérations sans verbe (« Identification, inventaire, traçabilité… »). Les sections sont titrées par la question à laquelle elles répondent (« Comment il maintient le froid »), pas avec le modèle « Thème : sous-thème », et on ne les découpe pas en #### parties d'un paragraphe : le #### est réservé au détail qui se plie.
• Structure visible, sans rompre la lecture : quand utiliser des cartes, de la prose, des sections, des encadrés, des tableaux ou des listes, le gras, les champs répétés et la typographie, dans crear_documentos (« Quand utiliser chaque ressource »). Dans un fondateur, les cartes typiques sont les expériences, les scénarios, les preuves, les phases, les portes, les dimensions d'une comparaison, les fiches et les chiffres clés du produit ; dans un bilan, ce qui a fonctionné est raconté en prose et les déficiences vont dans un tableau avec ce qui se passe et son état.
• Sans codes que le lecteur ne connaît pas encore. Les codes internes (S1, S2…) ne sont utilisés qu'après la section qui les définit et là où ils aident à croiser les références. Avant, et dans la prose qui argumente, on les exprime avec des mots (« le transport au domicile et la conservation à la maison »).
• Toute affirmation clé est justifiée au même endroit. Une thèse ou une conclusion importante indique sur quoi elle se base (les faits du document, avec chiffre et référence) et ce qui n'est pas encore démontré.
• Propositions, pas d'impositions. « On propose », « à évaluer », « décide qui de droit ».
• Respecte les sensibilités du domaine. Les règles du domaine du projet se trouvent dans les regles de son identité (les mêmes que lit documento_vision).

Comment on travaille

1. Lire avant de proposer : la vision du projet, son identité et ses règles, la spécification si elle existe, le code ou le jumeau s'ils apportent des chiffres, et le matériel apporté par l'auteur. Inventorier tous les arguments du projet. Un document fondateur de produit rassemble tous les arguments que le projet possède, et plus encore lorsqu'on compare avec d'autres produits : ceux des autres documents fondateurs, la vision, la spécification et ce qui est déjà construit (un jumeau numérique, un prototype, des tests). Avant d'écrire ou de réviser, on fait un inventaire de ce qui manque, avec sa source et sa classe (fait publié, objectif de conception, hypothèse ou avancée vérifiée uniquement par simulation), et des contradictions entre documents, qui sont demandées à l'auteur avant de transmettre tout chiffre affecté. Ce qui est construit est présenté avec ses limites déclarées.
2. Proposer le plan et les outils : demander si le document est un artefact pour le projet ou pour l'utilisateur et quels outils il comporte (moteur de recherche, notes, « Lecture », pliage, légende, édition…), avec la recommandation pour cette destination, en une seule question avec des options ; noter la réponse dans l'en-tête. Proposer le plan : le noyau, les sections optionnelles qui s'appliquent et pourquoi, les scénarios candidats avec leur code et les chiffres de couverture. Laisser l'auteur l'affiner avant d'écrire.
3. Rechercher les preuves manquantes (avec permission de chercher), avec leur source exacte.
4. Écrire le .md avec les ressources ci-dessous et générer le .html. Avant de remplacer une version, on la sauvegarde dans _respaldo/ (crear_documentos, « Sauvegarder »).
5. Vérifier (voir « Vérification ») et livrer avec un résumé : ce qu'il contient, ce qui est illustratif, quelles preuves manquent et ce qu'il convient de faire valider par un expert.
6. Affiner avec l'auteur. Chaque correction générale est ajoutée à cette compétence comme amélioration (ouverte à la SF).