Agents-On-Rails/compétences

/aor-req — Rédaction d'exigences

Rédige des UN, PR et SR suivant les patrons EARS-12, les attributs de qualité INCOSE C1-C9 et la syntaxe canonique de cross-référence. La sortie est en markdown.

Note sur les compétences vs les agents. Le bundle AOR contient des compétences dans .claude/skills/aor-*/SKILL.md (invocables directement, comme celle-ci) et des agents SME dans .claude/agents/aor-sme-*.md (prompts système de sous-agents générés uniquement par aor-review / aor-review-adhoc). N'invoquez PAS un agent en tant que compétence — cela échouera avec "compétence non trouvée".

Discipline de fonctionnement

Appliquez-la tout au long. Énoncez chaque point au démarrage pour que l'utilisateur le voie.

• Mode (déclaré au démarrage) : demandez s'il s'agit d'une session exploratoire (exigence unique, conversationnelle, sans fichiers) ou d'une session documentaire (rédaction complète de spécifications, fichiers écrits). Par défaut, explorez si le périmètre arrive sous forme de texte en ligne sans chemin de fichier, sinon document. Le mode contrôle si les étapes 5 à 7 écrivent sur le disque.
• Accusé de réception d'invocation : la première réponse de la compétence indique "Exécution de aor-req en mode . Les fichiers sont écrits dans sauf indication contraire." Élimine l'ambiguïté "la compétence a-t-elle vraiment été exécutée ?".
• Discipline Q&R : posez une question de clarification à la fois. Attendez la réponse de l'utilisateur avant d'en poser une autre. N'empilez pas les questions. Un seul appel AskUserQuestion présentant une décision avec plusieurs alternatives (par exemple, un menu à choix multiples) compte pour une question ; présenter deux décisions non liées en un seul appel constitue un empilement.
• Divulgation des échecs : si une étape prescrite ne peut pas être réalisée (écriture de fichier bloquée, invocation de sous-agent échouée, fichier de référence indisponible, achèvement partiel, délai d'attente dépassé, permission refusée), indiquez-le dans le chat. Après divulgation, arrêtez-vous et demandez s'il faut réessayer, revenir à une émulation manuelle divulguée, ou abandonner — ne continuez pas en silence. Une seule tentative est autorisée pour les pannes clairement transitoires (par exemple, délai d'attente réseau) avant divulgation obligatoire.

Flux de travail

Étape 1 : Établir le périmètre

Si l'utilisateur a passé un texte de périmètre ou un chemin de fichier, utilisez-le. Sinon, demandez via AskUserQuestion : "Quelles fonctionnalités ou modifications doivent être spécifiées ?"

Distinguer le texte de périmètre d'un chemin de fichier (REQ-B) : traitez l'entrée comme un chemin si (a) elle contient / ou \, (b) elle se termine par .md / .txt / .xlsx / .csv / .docx, ou (c) elle correspond à un fichier existant sur le disque via Read(). Sinon, traitez-la comme un texte de périmètre — y compris les descriptions multi-mots comme "système de réservation de rendez-vous patients".

Trancheur : si seule la règle (c) correspond (pas de / ou \, pas d'extension reconnue, mais Read() fonctionne) ET que l'entrée est un seul mot, confirmez avec l'utilisateur avant de considérer comme chemin : "Je vois qu'un fichier nommé <entrée> existe. Vouliez-vous dire ce fichier, ou s'agit-il d'une description de périmètre ?"

Pour les entrées provenant d'Excel, attendez-vous à ce que le LLM hôte ait transcrit les lignes dans un buffer markdown de travail avant l'exécution de cette compétence (le bundle n'analyse pas Excel directement).

Étape 1a : Classifier le niveau

En mode exploratoire, demandez :

"S'agit-il d'un besoin utilisateur (UN), d'une exigence produit (PR) ou d'une exigence logicielle (SR) ?"

Ignorez les étapes inutilisées une fois le niveau connu : la revue UN a besoin de l'étape 2 ; la revue PR a besoin de l'étape 3 + la porte Écho ; la revue SR a besoin des étapes 4 à 6.

Entrée multi-niveaux en mode exploratoire : si l'utilisateur fournit un ensemble UN+PR+SR (ou toute combinaison de plusieurs niveaux) au lieu d'en sélectionner un, traitez-le comme une revue multi-niveaux — parcourez les étapes 2 à 4 sur les niveaux fournis dans l'ordre, mais respectez la discipline d'écriture exploratoire (pas d'écriture automatique sur disque ; affichez les résultats en ligne).

En mode documentaire, par défaut, parcourez les trois niveaux (UN → PR → SR) aux étapes 2 à 4, sauf indication contraire de l'utilisateur.

Étape 2 : Rédiger les besoins utilisateurs (UN-NNN)

Pour chaque besoin distinct d'une partie prenante, rédigez un UN. Règles :

• Indépendant de la technologie, exprimé du point de vue de la partie prenante
• Narration simple (PAS de syntaxe EARS)
• Inclure un énoncé du problème (2-3 phrases) + un énoncé du besoin
• Taguez une personne via traces_to::UN->Persona [<persona-id>]
• Priorité : Critique | Haute | Moyenne | Basse

Voir templates.md pour le format.

Étape 3 : Rédiger les exigences produit (PR-NNN)

Pour chaque UN, dérivez des PR :

• Indépendantes de la technologie, mesurables, objectives
• Syntaxe EARS (voir ears-guide.md pour les 12 patrons)
• Chaque PR trace en arrière : derived_from::PR->UN [UN-NNN]
• Chaque PR trace en avant : traces_to::PR->SR [SR-NNN]
• Chaque PR de chemin heureux doit avoir au moins un compagnon If/Then (Indésirable)
• La même règle de compagnon If/Then s'applique au niveau SR à l'étape 4 — chaque SR de chemin heureux doit avoir un compagnon SR If/Then spécifiant la récupération au niveau de l'implémentation
• Chaque PR EARS-N (négatif/ne doit pas) doit avoir au moins un compagnon PR positif (Ubiquitaire, piloté par événement ou piloté par état) spécifiant le comportement correct attendu ; la même règle s'applique au niveau SR

"Chemin heureux" défini (REQ-E) : une PR est de chemin heureux si elle utilise l'un des patrons EARS positifs — Ubiquitaire, piloté par événement, piloté par état, Optionnel, Complexe, EARS-E, EARS-T, EARS-P. Exclus : Comportement indésirable, EARS-N (négatif/ne doit pas), EARS-F (déclaratif de mode de défaillance).

Exécutez la Décomposition d'erreur adversarial pour chaque UN :

1. Comment échoue-t-il silencieusement ?
2. Comment échoue-t-il bruyamment ?
3. Comment échoue-t-il sous charge ?
4. Comment échoue-t-il en cas de malveillance ?
5. Comment échoue-t-il avec le temps ?

Chaque mode de défaillance devient soit une PR EARS If/Then (taguez avec [ADV] dans l'en-tête ; l'identifiant reste canonique, par exemple PR-007 [ADV]) soit une note pour un registre des risques séparé.

Exemple concret. UN : "préserver chaque fichier téléversé". Mode de défaillance : "échoue silencieusement lorsque l'espace disque libre est épuisé". PR résultante :

### PR-007 [ADV] : Rejeter le téléversement lorsque la pression disque est élevée
Si l'espace disque libre descend en dessous de 5 %, alors le système doit rejeter les nouveaux
téléversements avec HTTP 507 Stockage insuffisant et retourner un en-tête Retry-After.
derived_from::PR->UN [UN-001]
traces_to::PR->SR [SR-014]

Notez que le mode de défaillance est concret et quantifié (5 %, HTTP 507, Retry-After) — c'est ce qui rend la PR vérifiable (C7).

Étape 4 : Rédiger les exigences logicielles (SR-NNN)

Pour chaque PR, dérivez des SR :

• Spécifiques à l'implémentation : nommez les services, API, bases de données, codes d'erreur
• Syntaxe EARS avec des noms de composants spécifiques
• Chaque SR trace en arrière : derived_from::SR->PR [PR-NNN]
• Chaque SR trace en avant : traces_to::SR->TC [TC-NNN]
• Utilisez une granularité au niveau des clauses (SR-NNN.c1, .c2) pour consolider les comportements liés sous un seul ID SR
• Chaque SR de chemin heureux doit avoir au moins un compagnon SR If/Then (Indésirable) (voir l'étape 3 pour la définition de "chemin heureux")
• Chaque SR EARS-N doit avoir au moins un compagnon SR positif

Étape 5 : Tableaux de spécification de champs

Pour les fonctionnalités avec saisie/affichage de données, ajoutez des tableaux de spécification de champs dans la section SR :

ID champ	Nom	Étiquette	Type	Min	Max	Unité	Par défaut	Requis	Exposition UI	Règle de validation	Message d'erreur	SR parent

Valeurs d'exposition UI : editable | display-only | hidden.

Étape 6 : Porte Écho

Pour chaque clause SR, rédigez une assertion testable d'une ligne :

VERIFY : [SR-NNN.c1] — [redite de l'exigence sous forme d'assertion testable]

Si vous ne pouvez pas rédiger l'assertion, l'exigence n'est pas testable — réécrivez-la.

Étape 7 : Vérification de complétude

Exécutez la liste de contrôle dans completeness.md avant de déclarer la rédaction terminée.

Gestion des entrées volumineuses

Lorsque l'entrée dépasse ~200 éléments sources (par exemple, un grand collage Excel) :

1. Divisez en lots de 50 lignes.
2. Pour chaque lot : a. Lisez le lot. b. Transcrivez en markdown UN/PR/SR selon les étapes ci-dessus. c. Ajoutez au fichier de travail (ne pas écraser). d. Signalez la progression : "Lot sur terminé ; exigences rédigées."
3. Après tous les lots, exécutez la vérification de complétude sur le fichier complet.

Si un lot contient une entrée ambiguë, faites une pause et demandez des éclaircissements avant de continuer — ne sautez pas de lignes en silence.

Chemins de sortie

Par défaut : ./requirements/SPECIFICATION.md pour le UN/PR/SR consolidé. L'utilisateur peut le remplacer.

Lors de la mise à jour d'un fichier existant, conservez les ID existants — ajoutez-en de nouveaux avec le numéro séquentiel suivant.

Syntaxe de cross-référence (aide-mémoire)

relation_type::SOURCE->TARGET [liste-ID]

Type	Direction	Utilisation
traces_to	avant	UN→PR, PR→SR, SR→TC, UN→Persona
derived_from	arrière	PR→UN, SR→PR, TC→SR
validates	vérification	TC→SR
mitigates	contrôle des risques	SR→RISQUE
conflicts_with	contradiction	n'importe→n'importe

Format d'identifiant

Regex : ^(UN|PR|SR|TC)-\d{3}(\.[A-Z])?$

• ID de base : UN-001, PR-001, SR-001
• Sous-ID (EARS-P tabulaire) : PR-010.A, PR-010.B
• Notation de clause : SR-001.c1, SR-001.c2

Fichiers de référence

• ears-guide.md — les 12 patrons EARS
• templates.md — modèles markdown pour les sections UN/PR/SR
• completeness.md — liste de contrôle de sortie (couverture UN→PR→SR)