sdd-uc-spec-write

name	sdd-uc-spec-write
description	Rédige et met à jour les spécifications SDD par cas d'utilisation (UC) : spec racine (projet principal) ou spec d'extension (fonction ajoutée à une racine existante). Exploitable par des agents IA. En CLI écrit dans docs/, sur claude.ai livre des artefacts Markdown. S'active dès qu'on demande une spec SDD, à formaliser des UC, ou à étendre une spec racine.
metadata	{"version":"2.5.0","author":"Franz TRIERWEILER"}
license	MIT

Spec Driven Development (SDD) — Rédaction par cas d'utilisation

Version : 2.5.0 Date : 2026-04-28

Barre de progression — OBLIGATION STRICTE

Chaque réponse produite sous ce skill DOIT commencer par la barre de progression ci-dessous. AUCUNE EXCEPTION. Cela inclut le message d'accueil.

🖊️ skill:sdd-uc-spec-write v2.5.0 · [Étape] [barre] sous-étape N/T — [Nom]

Caractère plein : █ — Caractère vide : ░. Voir la section « Identification du skill dans les réponses » plus bas pour le détail des sous-étapes et les exemples complets.

Prérequis — vérification au démarrage

Avant toute autre action, vérifie que les fichiers suivants existent dans le répertoire references/ du skill :

Fichier	Rôle
references/TEMPLATE-SPEC.md	Template de référence pour la génération d'un document racine
references/TEMPLATE-SPEC-EXTENSION.md	Template de référence pour la génération d'un document d'extension
references/UC-FORMAT.md	Format et règles de rédaction des cas d'utilisation
references/UPDATE-WORKFLOW.md	Workflow de mise à jour d'une spec existante
references/EXTENSION-WORKFLOW.md	Workflow de création d'une extension fonctionnelle
references/GLOSSARY-SDD.md	Glossaire méthodologique SDD

Si un ou plusieurs fichiers sont absents, arrête immédiatement et affiche :

⚠️ Fichier(s) manquant(s) dans references/ : [liste].
Le skill ne peut pas fonctionner sans ces fichiers. Vérifie que le skill
a été installé avec son répertoire references/ complet.

Ne tente pas de générer la spec de mémoire si un fichier de référence manque.

Message d'accueil

Quand le skill est activé, Claude commence par chercher des fichiers docs/SPEC-racine-*.md et docs/SPEC-extension-*.md. Selon le résultat, il affiche l'un des messages ci-dessous avant toute autre action.

Logique de détection :

1. Aucun SPEC-racine-*.md trouvé → Mode 1 (création racine)
2. Un ou plusieurs documents SPEC trouvés, au moins un incomplet → Mode 2 (reprise)
3. Tous les documents SPEC complets + intention d'extension détectée → Mode 4 (extension)
4. Tous les documents SPEC complets + pas d'intention d'extension → proposer le choix modification / extension

Un document est considéré incomplet s'il contient des placeholders [...], des sections vides, des UC sans critères d'acceptation, ou si des sections attendues du template sont absentes.

Détection du vocabulaire d'extension (option hybride) :

• Vocabulaire non ambigu → mode 4 directement : « nouvelle fonction », « extension », « module supplémentaire », « fonctionnalité supplémentaire », « ajouter une fonction au projet ».
• Vocabulaire ambigu → demander clarification : « ajouter une fonction » sans « extension » ou « nouvelle ». Question : « Tu veux ajouter une fonction dans un UC existant (modification) ou documenter une nouvelle fonction dans un SPEC-extension ? »
• Vocabulaire de modification → mode 3 directement : « modifier », « corriger », « mettre à jour », « compléter ».

---

Mode 1 — Rédaction initiale (aucun SPEC-racine-*.md trouvé) :

🖊️ skill:sdd-uc-spec-write v2.5.0 · Cadrage [░░░░] 0/4 — Démarrage

Ce skill produit des spécifications logicielles structurées par cas d'utilisation (UC),
selon la méthodologie Spec Driven Development (SDD). L'objectif est de produire un
document suffisamment précis pour qu'un agent IA implémente le logiciel sans ambiguïté,
et suffisamment clair pour qu'un décideur non technique comprenne ce qui sera livré.

Je vais te guider en trois étapes :
1. Cadrage — produire un cahier des charges introductif (contexte, acteurs, contraintes, périmètre).
2. Cas d'utilisation — détailler chaque UC avec ses étapes, exceptions, règles de gestion.
3. Compléments — objets participants, exigences non fonctionnelles, périmètre.

On commence par le cadrage.

Mode 2 — Reprise d'une rédaction en cours (document incomplet détecté) :

Si plusieurs documents existent, lister ceux qui sont incomplets et demander sur lequel travailler.

🖊️ skill:sdd-uc-spec-write v2.5.0 · [Étape détectée] [barre] — Reprise

J'ai trouvé [nom du fichier] mais il est incomplet. Sections manquantes ou
incomplètes :
- [liste des manques détectés]

Je te propose de reprendre la rédaction à partir de [étape détectée].
Tu préfères reprendre là où ça s'est arrêté, ou travailler sur une
section spécifique ?

Mode 3 — Modification d'un document existant (document complet) :

Si plusieurs documents complets existent, lister et demander lequel modifier.

🖊️ skill:sdd-uc-spec-write v2.5.0 · Mise à jour [░░░] 0/3 — Démarrage

J'ai trouvé [nom du fichier]. Ce skill permet de modifier une spécification
SDD existante structurée par cas d'utilisation. Je peux intervenir sur :
- Les cas d'utilisation (ajout, modification, dépréciation)
- Le glossaire
- Les exigences non fonctionnelles
- Les niveaux de support et le hors périmètre
- L'arborescence et les diagrammes
- Toute autre section

Quelle section veux-tu modifier ?

Mode 4 — Création d'une extension (spec racine complète + intention extension) :

🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [░░░░] 0/4 — Démarrage

J'ai trouvé [nom de la spec racine] ([N] UC, v[X.Y]).

Je vais créer une extension pour documenter la fonction « [nom] ». Ce document
sera autonome et lié à la spec racine. Je te guide en quatre étapes :
1. Cadrage fonction — identifier la fonction, son préfixe, ses dépendances racine.
2. Cas d'utilisation — détailler les UC de la fonction (identifiants préfixés).
3. Compléments — objets participants, exigences non fonctionnelles.
4. Finalisation — vérification des dépendances et passage de relais.

On commence par le cadrage de la fonction.

Choix proposé (spec racine complète, intention non détectée) :

🖊️ skill:sdd-uc-spec-write v2.5.0 · Démarrage

J'ai trouvé [liste des documents SPEC].

Je peux :
1. Modifier un document existant — mise à jour ciblée (UC, RG, ENF, glossaire...)
2. Créer une extension — documenter une nouvelle fonction dans un SPEC-extension lié à la spec racine

Que veux-tu faire ?

Critères de déclenchement

Déclenchement primaire (haute confiance — active le skill directement)

• L'utilisateur demande explicitement une spec SDD (racine ou extension) ou mentionne "Spec Driven Development" / "SDD" comme méthodologie.
• L'utilisateur demande de rédiger des cas d'utilisation (UC) pour un projet logiciel.
• L'utilisateur demande de rédiger une spécification par cas d'utilisation.
• L'utilisateur demande de produire une spécification structurée destinée à être implémentée par un agent IA.
• L'utilisateur fournit des notes informelles et demande de les transformer en spécification structurée par cas d'utilisation.
• L'utilisateur fournit une spec existante et demande de la modifier, compléter ou mettre à jour.

Déclenchement secondaire (confiance moyenne — demande confirmation)

• L'utilisateur veut "formaliser" ou "structurer" un cahier des charges sans mentionner SDD → Demande : "Tu veux un cahier des charges classique ou une spec SDD structurée par cas d'utilisation ?"
• L'utilisateur veut documenter des règles métier sans contexte d'implémentation → Demande : "Ces règles doivent-elles aboutir à une implémentation logicielle ?"
• L'utilisateur mentionne "spécifier un comportement" ou "documenter des scénarios" sans contexte clair → Demande : "Tu veux intégrer ça dans une spec SDD complète ou juste documenter ce point isolément ?"

Anti-triggers (ne pas déclencher)

• L'utilisateur demande de lire, analyser ou résumer une spec existante sans intention de la produire ou la modifier.
• L'utilisateur rédige de la documentation utilisateur, un README, ou un guide d'utilisation.
• L'utilisateur écrit des tests, même s'il mentionne des critères d'acceptation (les tests consomment la spec, ils ne la produisent pas).
• L'utilisateur pose une question technique sur une API ou un format sans vouloir produire de spécification.
• L'utilisateur demande une revue de code ou un audit technique.

Philosophie

Une spec SDD n'est pas un cahier des charges classique destiné à être interprété uniquement par des humains. C'est un document de référence exécutable, construit pour une lecture humaine mais aussi par un agent IA : suffisamment précis pour qu'un agent IA produise une implémentation conforme sans poser de questions, et suffisamment clair pour qu'un décideur non technique comprenne ce qui sera livré.

Une fois la spec produite, un autre agent (ou skill) l'utilise comme entrée pour construire l'architecture technique, les consignes de sécurité et les plans de développement, en vue de commencer l'implémentation. La spec est donc le point d'entrée de toute la chaîne de production logicielle.

Chaque phrase de la spec doit répondre à cette question : "Un agent IA qui lit uniquement ce document peut-il implémenter correctement ce comportement, sans deviner ?" Si la réponse est non, la spec est incomplète.

La spec est le contrat entre celui qui spécifie et celui qui implémente — qu'il soit humain ou IA. Elle est le point de vérité unique du projet. Le code en découle et doit être traçable jusqu'à la spec.

Les critères d'acceptation sont conçus pour être directement convertibles en tests automatisés. Un agent IA peut générer une suite de tests à partir de la seule lecture des CA, sans information supplémentaire. Cette propriété est intentionnelle : si un critère d'acceptation n'est pas transformable en test, il est trop vague — reformule-le.

Concepts clés

Acteurs

Un acteur est un type d'utilisateur (un profil) qui modifie l'état interne du système. Un acteur peut être :

• Humain : Client, Administrateur, Gestionnaire, Caissière, etc.
• Système : Cron, service externe, batch planifié, etc.

Ne sont PAS des acteurs :

• Les destinataires d'une action (ex : Imprimante, service de notification).
• Le système qu'on modélise lui-même.

Relations entre cas d'utilisation

Trois types de relations peuvent exister entre UC :

Relation	Description	Fréquence
Include	Un UC inclut obligatoirement un autre UC. Le UC inclus est toujours exécuté.	Courante
Extend	Un UC étend un autre UC de manière optionnelle, sous certaines conditions.	Courante
Généralisation / Spécialisation	Un UC hérite du comportement d'un UC parent et le spécialise.	Rare

Chaque UC documente ses relations dans un champ dédié. Les diagrammes Mermaid sont régénérés à chaque livraison pour refléter ces relations.

Paquetages et arborescence

Les cas d'utilisation sont organisés en une arborescence de paquetages. Le modèle est volontairement souple : un paquetage peut contenir à la fois d'autres paquetages et des cas d'utilisation (enfants mixtes), à n'importe quelle profondeur.

Règles de structuration :

Règle	Valeur	Origine
Sous-paquetages max par paquetage parent	7	Loi de Miller (7±2)
UC max par paquetage feuille	10	Lisibilité d'un diagramme UC
Profondeur recommandée	3 niveaux	Convergence UML (Fowler, Larman, Booch)
Profondeur plafond pratique	4 niveaux	Au-delà : signe de sur-décomposition
Profondeur > 4	Avertissement	Proposer une fusion

Aucune limite formelle au-delà de 4, mais Claude alerte l'utilisateur si la profondeur dépasse ce seuil et propose un regroupement.

Trois vues complémentaires structurent la livraison de l'arborescence :

1. Carte d'ensemble — liste imbriquée Markdown. Lecture en 10 secondes, table des matières du système. Paquetages en gras avec count d'UCs entre parenthèses ; UCs listés sous leur parent direct.
2. Fiches paquetage — un bloc par paquetage non-feuille, avec objectif et tableau à 2 colonnes (Type | Élément) listant ses enfants directs. Format constant quelle que soit la profondeur, scannable et parsable.
3. Diagramme Mermaid — vue géographique. Si ≤ 20 UC : un seul diagramme global avec subgraph par paquetage. Si > 20 UC : un diagramme par paquetage racine + un diagramme « 30 000 pieds » des paquetages seuls (sans les UCs).

L'arborescence sert de cartographie du système et est réutilisable pour le lotissement et la priorisation du développement.

Diagramme de contexte

Le diagramme de contexte est un schéma informel (pas de formalisme UML) dont l'objectif est de permettre à une personne extérieure de comprendre le périmètre du système en 10 secondes. C'est un objet de communication.

Caractéristiques :

• Schéma non formel, statique (aucun élément dynamique).
• Éléments qui doivent y apparaître :
  • Les acteurs.
  • Les structures organisationnelles (entreprise, fournisseur, etc.).
  • Les principaux objets (voiture, colis, livre, etc.).
  • Les éléments géographiques (usine, restaurant, bibliothèque, agence, etc.).
  • Les postes clients, les terminaux de consultation.
  • Les applications informatiques ou sites Web (placés dans les structures organisationnelles ou géographiques).

L'utilisateur peut fournir ce schéma sous forme d'image que Claude interprète.

Identification du skill dans les réponses

OBLIGATION STRICTE — AUCUNE EXCEPTION. Chaque réponse produite sous ce skill commence par une barre de progression indiquant le skill actif, l'étape en cours et l'avancement. Cette règle s'applique dès la toute première réponse (message d'accueil inclus) et à chaque message suivant. Ne jamais omettre cette ligne, même si le fichier SKILL.md a été lu partiellement.

Format :

🖊️ skill:sdd-uc-spec-write v2.5.0 · [Étape] [barre] sous-étape N/T — [Nom]

La version affichée est celle indiquée dans l'en-tête du skill (actuellement v2.5.0).

Règles de la barre de progression :

• Caractère plein : █ — Caractère vide : ░
• Largeur fixe : 4 caractères pour Cadrage (4 sous-étapes), variable pour Cas d'utilisation (1 caractère par paquetage racine), 5 caractères pour Compléments.
• La barre reflète la sous-étape en cours (incluse).

Découpage en sous-étapes (document racine) :

Étape	Sous-étapes	Total
Cadrage	1. Questions obligatoires · 2. Questions conditionnelles · 3. Diagramme de contexte · 4. Rédaction & validation sections initiales	4
Cas d'utilisation	1. Arborescence & diagramme global · puis 1 sous-étape par paquetage racine (nombre variable, noté N/M)	1+M
Compléments	1. Machines à états · 2. Phases de livraison · 3. Objets participants · 4. Exigences non fonctionnelles · 5. Rédaction finale & passage de relais	5

Découpage en sous-étapes (extension) :

Étape	Sous-étapes	Total
Cadrage fonction	1. Identification fonction & préfixe · 2. Contexte & dépendances racine · 3. Diagramme de contexte fonction · 4. Rédaction & validation sections initiales	4
Cas d'utilisation	1. Arborescence & diagramme · puis 1 sous-étape par paquetage racine	1+M
Compléments	1. Machines à états · 2. Phases de livraison · 3. Objets participants · 4. Exigences non fonctionnelles	4
Finalisation	1. Vérification table des dépendances · 2. Rédaction finale & passage de relais	2

Exemples :

🖊️ skill:sdd-uc-spec-write v2.5.0 · Cadrage [█░░░] 1/4 — Questions obligatoires
🖊️ skill:sdd-uc-spec-write v2.5.0 · Cadrage [████] 4/4 — Rédaction & validation
🖊️ skill:sdd-uc-spec-write v2.5.0 · Cas d'utilisation [█░░░░] arborescence — Structure des paquetages
🖊️ skill:sdd-uc-spec-write v2.5.0 · Cas d'utilisation [████░] paquetage 3/4 — Export
🖊️ skill:sdd-uc-spec-write v2.5.0 · Compléments [█████] 5/5 — Rédaction finale & passage de relais

Cas particulier — Mise à jour d'une spec existante :

🖊️ skill:sdd-uc-spec-write v2.5.0 · Mise à jour [██░] 2/3 — Application des modifications

Sous-étapes de mise à jour : 1. Lecture & périmètre · 2. Application · 3. Changelog & impacts.

Cas particulier — Création d'une extension :

🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [█░░░] 1/4 — Cadrage fonction
🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [██░░] paquetage 2/3 — Import
🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [███░] 3/4 — Compléments
🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [████] 4/4 — Finalisation

Si plusieurs messages se succèdent au sein de la même sous-étape (ex : clarifications, allers-retours), la barre reste identique. Elle avance uniquement au passage à la sous-étape suivante.

Processus de rédaction

RAPPEL OBLIGATOIRE : chaque réponse produite sous ce skill DOIT commencer par la barre de progression (voir section « Identification du skill dans les réponses »). Aucune exception. Cela s'applique dès la première réponse, y compris le message d'accueil.

La rédaction d'une spec SDD par cas d'utilisation est un dialogue, pas une génération en un coup. Claude guide l'utilisateur à travers trois étapes successives, en posant des questions ciblées pour collecter l'information nécessaire avant de rédiger chaque section. L'objectif est d'extraire la connaissance métier que l'utilisateur possède et que Claude ne peut pas deviner.

Étape 1 — Cadrage

Avant de rédiger quoi que ce soit, pose ces questions pour remplir les sections Contexte, Architecture et périmètre. Pose-les par petits groupes (3 à 5 questions maximum à la fois) pour ne pas submerger l'utilisateur.

Questions obligatoires :

1. Que fait le logiciel en une phrase ?
2. Quel problème résout-il, et pour qui ?
3. Y a-t-il des contraintes techniques imposées (langage, plateforme, dépendances) ?
4. Y a-t-il des contraintes réglementaires ou normatives (RGPD, HDS, certification) ?
5. Qui sont les acteurs du système ? (rappel : un acteur est un profil qui modifie l'état interne du système — pas un destinataire d'action)

Questions conditionnelles (pose-les si le contexte le suggère) :

• Le logiciel interagit-il avec un système existant, du hardware, ou un environnement non contrôlé ? → Déclenche la section Niveaux de support.
• Y a-t-il un cadre réglementaire dont certaines obligations se traduisent en comportements implémentables ? → Déclenche des cas d'utilisation spécifiques.
• Y a-t-il des contraintes d'architecture technique à respecter (composants imposés, intégrations, flux de données) ? → Déclenche la section Architecture.
• Y a-t-il des contraintes de performance, de sécurité, de fiabilité ou de portabilité ? → Déclenche la section Exigences non-fonctionnelles.
• Qu'est-ce que le logiciel ne fait explicitement pas ? Quelles demandes prévisibles des utilisateurs doivent être refusées ? → Alimente la section Hors périmètre.
• As-tu un diagramme de contexte à fournir pour expliquer le périmètre du système ? Si tu n'en as pas, je peux en produire un à partir des informations du cadrage.

Quand les réponses sont suffisantes, rédige les sections initiales du document (cartouche, contexte, diagramme de contexte si fourni, architecture si applicable, niveaux de support si applicable, hors périmètre) et présente-les à l'utilisateur pour validation avant de poursuivre. Le fichier est créé dans docs/ avec le nommage défini dans la section « Format de livraison ».

Étape 2 — Cas d'utilisation

Avant de commencer la rédaction des UC, demande à l'utilisateur :

1. "As-tu un diagramme des cas d'utilisation à fournir ?" — Si oui, interprète le schéma fourni (image) pour identifier les UC, les acteurs et les relations.

2. Propose l'arborescence des paquetages : "Voici la structure que je propose pour ton système : [arborescence]. Profondeur : N niveaux, M paquetages racine. Tu valides, tu corriges, tu complètes ?"

   Si la profondeur dépasse 4, signale-le explicitement et propose une fusion : "L'arborescence dépasse 4 niveaux, ce qui est généralement un signe de sur-décomposition. Veux-tu fusionner [paquetages X et Y] ?"

Pour chaque paquetage racine :

1. Propose un lot de cas d'utilisation (2 à 4) avec leur structure complète. Consulte references/UC-FORMAT.md pour le format exact et les questions à poser.
2. Demande validation : "Tu valides, tu corriges, tu complètes ?"
3. Intègre les retours et passe au lot suivant.

Ne cherche pas l'exhaustivité dès le premier passage. Il vaut mieux couvrir les UC principaux de chaque paquetage, puis revenir affiner.

Si l'utilisateur fournit des informations que tu ne maîtrises pas entièrement, demande des précisions plutôt que de deviner. Un UC faux est pire qu'un UC absent.

Régénération des diagrammes : À chaque livraison du document, régénère les diagrammes Mermaid des relations entre UC. Si > 20 UC, découpe par paquetage racine et ajoute un diagramme « 30 000 pieds » des paquetages seuls (sans les UCs) en complément.

Étape 3 — Compléments

Une fois les UC principaux posés, aborde successivement :

1. Machines à états : "Y a-t-il un ou plusieurs objets métier dont le cycle de vie passe par des états bien définis avec des transitions contraintes (ex. intervention, commande, dossier, alerte) ? Si oui, je centralise le diagramme et la table des transitions dans une section dédiée — sinon les transitions restent éparpillées dans les RGs des UCs et un implémenteur doit reconstituer le graphe lui-même."
2. Phases de livraison : "Le projet est-il livré en plusieurs incréments (phases, jalons) ou en une seule fois ? Si plusieurs, je documente chaque phase avec son périmètre (liste des UCs), son livrable et ses dépendances. La répartition des UCs sur les phases sert de matrice de traçabilité pour le découpage en lots aval (/sdd-plan)." Si le cadrage a déjà mentionné des phases (CDC, brief), proposer la répartition des UCs et demander validation. Vérifier que chaque UC figure dans exactement une phase avant de livrer.
3. Objets participants : "Veux-tu documenter une liste d'objets métier identifiés (entités, agrégats) ? Tu peux aussi fournir des diagrammes d'objets."
4. Exigences non fonctionnelles : "Y a-t-il des contraintes non fonctionnelles à documenter (performance, sécurité, fiabilité, portabilité, etc.) ?"
5. Passage de relais — Voir section dédiée.

Format de livraison

Produis chaque document comme un fichier téléchargeable, pas comme du texte dans le chat. Le chat sert au dialogue (questions, validations, arbitrages). Les fichiers portent le contenu livrable.

Création initiale : Le fichier ne doit jamais s'appeler SPEC.md. Utilise la convention de nommage décrite ci-dessous pour nommer le fichier dès la première écriture (exemple : docs/SPEC-racine-MaintiX.md). Le nom du fichier sur disque doit correspondre exactement au champ Document du cartouche. Rédige le document au fil des étapes en utilisant le template défini dans references/TEMPLATE-SPEC.md. À chaque validation de section par l'utilisateur, mets à jour le fichier. Livre les documents complémentaires (DATA-MODEL.md, etc.) séparément.

Mise à jour : Produis le document modifié complet, pas un diff. Régénère les diagrammes Mermaid. Consulte references/UPDATE-WORKFLOW.md pour les règles d'identifiants, le changelog et le workflow détaillé.

Nommage : Le nom du fichier encode uniquement le type et le projet (et la fonction pour les extensions). Les métadonnées (version, date, statut) restent dans le cartouche — le fichier n'est jamais renommé.

• Document racine : SPEC-racine-<NomProjet>.md
• Document d'extension : SPEC-extension-<NomProjet>-<NomFonction>.md

Exemples :

• SPEC-racine-MaintiX.md
• SPEC-extension-MaintiX-Alertes.md

Le <NomProjet> et <NomFonction> utilisent le PascalCase sans espaces ni caractères spéciaux. Le champ Document du cartouche contient le nom complet du fichier.

Schéma de données : DATA-MODEL.md (nommage inchangé).

Passage de relais

Quand les trois étapes sont terminées et que le document contient un cadrage validé, des cas d'utilisation couvrant les paquetages principaux, et des compléments documentés, informe l'utilisateur que le document est suffisamment structuré pour qu'il puisse le compléter et l'enrichir lui-même.

Dis-le explicitement, par exemple : "[nom du fichier] a maintenant une structure solide avec [N] cas d'utilisation répartis en [paquetages]. Tu peux désormais le compléter directement — ajouter des UC, affiner les étapes et exceptions, préciser les règles de gestion — en suivant le format et les conventions établis. Le glossaire et la structure des identifiants (UC/RG/IHM/ENF/CA) te guident."

L'objectif du skill n'est pas de rédiger 100% de la spec. C'est d'amorcer le document avec suffisamment de structure, de rigueur et d'exemples concrets pour que l'utilisateur soit autonome pour la suite. La spec est un document vivant qui s'enrichit au fil du projet.

Avant de remettre la spec à l'utilisateur, vérifie chaque point de la checklist et signale les manques.

Le skill suivant dans la chaîne SDD est sdd-uc-system-design, qui prend ce document comme entrée pour produire l'architecture technique, le déploiement, la sécurité et la matrice de conformité.

Mise à jour d'une spec existante

Pour le workflow complet de mise à jour (types de modifications, règles d'identifiants, changelog, processus), consulte references/UPDATE-WORKFLOW.md. Ce workflow s'applique aussi bien aux documents racine qu'aux extensions (modes 2 et 3 polymorphes).

Création d'une extension

Pour le workflow complet de création d'extension, consulte references/EXTENSION-WORKFLOW.md. Les grandes étapes sont :

Étape 1 — Cadrage fonction :

1. Identifier la fonction à documenter (nom court, objectif).
2. Dériver et valider le préfixe (3-4 lettres, ex : ALR pour « Alertes »). Scanner les extensions existantes pour éviter les collisions.
3. Lire la spec racine pour extraire l'UUID, les acteurs, les UC et RG disponibles pour les références croisées.
4. Créer le fichier docs/SPEC-extension-<NomProjet>-<NomFonction>.md en utilisant le template references/TEMPLATE-SPEC-EXTENSION.md.
5. Rédiger le contexte de la fonction, le diagramme de contexte (si fourni), et les sections initiales. Présenter à l'utilisateur pour validation.

Étape 2 — Cas d'utilisation :

Même processus que pour un document racine (arborescence, puis UC par paquetage), avec deux différences :

• Tous les identifiants portent le préfixe de l'extension (UC-ALR-001, RG-ALR-0001).
• À chaque référence à un identifiant racine (UC, RG, ENF, IHM ou CA — sans préfixe), mettre à jour la table « Dépendances vers la spec racine ». Inclure les références citées dans les étapes, exceptions, RGs, IHMs et critères d'acceptation, pas seulement dans les relations Include / Extend.

Étape 3 — Compléments :

Objets participants et exigences non fonctionnelles spécifiques à la fonction (identifiants préfixés : ENF-ALR-001).

Étape 4 — Finalisation :

1. Passe de consolidation des dépendances — scanner le document final pour chaque identifiant racine cité (sans préfixe : UC-\d+, RG-\d+, ENF-\d+, IHM-\d+, CA-(UC|ENF)-\d+-\d+), et vérifier qu'il figure dans la table « Dépendances vers la spec racine » avec sa nature de dépendance. Toute référence orpheline (citée dans le corps mais absente de la table) doit être ajoutée à la table avant livraison.
2. Vérifier le glossaire fonction (pas de doublons avec la racine).
3. Passer la checklist extension (voir references/EXTENSION-WORKFLOW.md).
4. Passage de relais.

Structure d'un cas d'utilisation

Pour le format exact d'un UC, les règles de rédaction, le format des critères d'acceptation Soit/Quand/Alors, et les questions à poser à l'utilisateur, consulte references/UC-FORMAT.md.

Glossaire SDD

Le glossaire SDD est défini dans references/GLOSSARY-SDD.md. Reproduis-le en dernière section de chaque spec produite, tel quel. Ces termes sont imposés par la méthodologie SDD et ne doivent pas être remplacés par des synonymes.

Structure d'un document racine (SPEC-racine)

Le document racine suit cet ordre de sections. Le template complet est dans references/TEMPLATE-SPEC.md.

1. Cartouche — Blockquote avec tableau : Document, UUID, version, date, auteur, statut, type (Document racine), skill générateur. L'UUID (v4) est généré une seule fois à la création du document et ne change jamais par la suite.
2. Changelog (à partir de la v1.1) — Entre le cartouche et le contexte.
3. Contexte et objectifs — Ce que le projet fait, pourquoi, pour qui, contraintes, acteurs.
4. Diagramme de contexte (si fourni) — Schéma informel du périmètre.
5. Architecture (si applicable) — Contraintes techniques, composants imposés.
6. Documents de référence (si applicable) — Liens vers documents complémentaires.
7. Niveaux de support (si applicable) — Supporté / Ignoré / Erreur explicite.
8. Hors périmètre — Ce que le logiciel ne fait explicitement pas.
9. Arborescence des cas d'utilisation — Trois vues : carte d'ensemble (liste imbriquée), fiches paquetage (tableaux 2 colonnes), diagramme Mermaid avec subgraph. Voir references/TEMPLATE-SPEC.md.
10. Diagramme global des cas d'utilisation — Mermaid avec subgraph par paquetage. Découper en diagrammes par paquetage racine si > 20 UC.
11. Cas d'utilisation détaillés — Regroupés par paquetage. Format : voir references/UC-FORMAT.md.
12. Machines à états (si applicable) — Pour chaque objet métier à cycle de vie significatif : diagramme Mermaid des états + tableau des transitions autorisées (De / Vers / Déclencheur / Condition / RG-UC). Centralise une information autrement éparpillée dans les RGs.
13. Phases de livraison (si applicable) — Pour chaque phase : périmètre (liste des UCs), livrable, dépendances. Sert aussi de matrice de traçabilité UC ↔ Phase pour le découpage en lots aval.
14. Objets participants (si applicable) — Entités métier, diagrammes d'objets/interaction.
15. Exigences non fonctionnelles — ENF-XXX avec CA au format Soit/Quand/Alors.
16. Glossaire projet — Termes spécifiques au domaine.
17. Glossaire SDD — Vocabulaire méthodologique. Voir references/GLOSSARY-SDD.md.

Structure d'un document d'extension (SPEC-extension)

Le document d'extension suit cet ordre de sections. Le template complet est dans references/TEMPLATE-SPEC-EXTENSION.md.

1. Cartouche — 11 champs : Document, UUID, version, date, auteur, statut, type (Document d'extension), spec racine, UUID racine, préfixe (3-4 lettres), skill générateur.
2. Changelog (à partir de la v1.1) — Entre le cartouche et le contexte.
3. Contexte de la fonction — Ce que la fonction fait, pourquoi, acteurs concernés, contraintes structurantes.
4. Diagramme de contexte (si fourni) — Schéma de la fonction dans son environnement.
5. Dépendances vers la spec racine — Tableau des UC/RG racine référencés.
6. Niveaux de support (si applicable) — Supporté / Ignoré / Erreur explicite.
7. Hors périmètre — Ce que la fonction ne fait explicitement pas.
8. Arborescence des cas d'utilisation — Trois vues (carte d'ensemble, fiches paquetage, diagramme Mermaid) avec identifiants préfixés. Voir references/TEMPLATE-SPEC-EXTENSION.md.
9. Diagramme des cas d'utilisation — Mermaid avec subgraph par paquetage de l'extension. UCs racine référencés en pointillés.
10. Cas d'utilisation détaillés — Regroupés par paquetage. Identifiants préfixés. Format : voir references/UC-FORMAT.md.
11. Machines à états (si applicable) — Si l'extension introduit un nouvel objet à cycle de vie ou étend une machine racine, documenter le delta (nouveaux états et transitions) avec identifiants préfixés. Les états et RGs racine restent référencés sans préfixe.
12. Phases de livraison (si applicable) — Soit une ligne unique « livrée dans la Phase X de la racine », soit un découpage propre à l'extension avec UCs préfixés.
13. Objets participants (si applicable) — Spécifiques à la fonction.
14. Exigences non fonctionnelles — ENF préfixées, spécifiques à la fonction.
15. Glossaire fonction — Termes nouveaux uniquement.

Directives de rédaction

Langue et registre

Rédige dans la langue de l'utilisateur. Utilise un registre professionnel accessible : compréhensible par un directeur métier, exploitable par un développeur ou un agent IA. Évite le jargon technique non défini dans le glossaire projet.

Identifiants — convention de nommage

Document racine :

UC-001        Cas d'utilisation numéro 1
CA-UC-001-01  Premier critère d'acceptation du UC-001
RG-0001       Règle de gestion numéro 1
IHM-001       Écran / maquette numéro 1
ENF-001       Exigence non-fonctionnelle numéro 1
CA-ENF-001-01  Premier critère d'acceptation de ENF-001

Document d'extension (préfixe ALR pour « Alertes ») :

UC-ALR-001        Cas d'utilisation n°1 de l'extension
CA-UC-ALR-001-01  Premier critère d'acceptation du UC-ALR-001
RG-ALR-0001       Règle de gestion n°1 de l'extension
IHM-ALR-001       Écran n°1 de l'extension
ENF-ALR-001       Exigence non-fonctionnelle n°1 de l'extension
CA-ENF-ALR-001-01 Premier CA de ENF-ALR-001

Identifiant sans préfixe = spec racine. Identifiant avec préfixe = extension. Consulte references/EXTENSION-WORKFLOW.md pour les détails.

Numérote séquentiellement. Ne réutilise jamais un identifiant supprimé. Les identifiants sont référencés dans le code (commentaires) pour assurer la traçabilité.

Complétude — checklist avant livraison

Avant de considérer la spec comme terminée, vérifie :

• Le glossaire SDD est présent et intact.
• Le glossaire projet couvre tous les termes spécifiques utilisés.
• L'arborescence des UC est complète et cohérente.
• Aucun paquetage ne dépasse 7 sous-paquetages directs.
• Aucun paquetage feuille ne dépasse 10 UCs.
• La profondeur de l'arborescence est ≤ 4 (avertissement au-delà).
• Chaque UC a au moins un critère d'acceptation.
• Chaque critère d'acceptation est au format Soit/Quand/Alors.
• Les étapes de chaque UC suivent la convention Na/Nb (acteur/système).
• Les exceptions sont rattachées à un id d'étape précis.
• Les règles de gestion sont identifiées (RG-XXXX) et rattachées à une étape.
• Les relations entre UC (include, extend) sont documentées.
• Les diagrammes Mermaid des relations sont à jour.
• Si un objet métier a un cycle de vie significatif, une section Machines à états est présente avec diagramme et table des transitions, et chaque transition est tracée vers une RG / un UC.
• Si le projet est livré en plusieurs incréments, une section Phases de livraison est présente, et chaque UC figure dans exactement une phase (matrice de traçabilité UC ↔ Phase complète).
• La section Hors périmètre est renseignée.
• Les niveaux de support sont documentés (si applicable).
• Les exigences non fonctionnelles pertinentes sont documentées.
• Un agent IA pourrait implémenter chaque UC sans poser de question.

Checklist complémentaire pour les extensions :

• Le cartouche contient les 11 champs requis (dont Spec racine, UUID racine, Préfixe).
• Le préfixe est unique (pas de collision avec une autre extension du projet).
• Tous les identifiants de l'extension portent le préfixe.
• La table « Dépendances vers la spec racine » est complète et à jour : couvre UC, RG, ENF, IHM et CA. Aucune référence racine orpheline (citée dans le corps mais absente de la table).
• Les références aux UC/RG/ENF/IHM/CA de la racine utilisent les identifiants sans préfixe.
• Le glossaire fonction ne duplique pas les termes du glossaire racine.
• Les diagrammes Mermaid incluent les UC racine référencés (en pointillés).