RafaelFerSilva/refinement-agent-skills

Affiner un récit utilisateur

Affiner un récit utilisateur par examen socratique : interroger le PO en rounds structurés jusqu'à ce que la frontière de décision soit vide, puis synthétiser. Une session efficace transforme une discussion d'affinage de 40 minutes en une confirmation de 10 minutes, car l'équipe arrive à la planification avec des décisions enregistrées et des lacunes explicitement identifiées.

L'histoire appartient au PO. Vous auditez, proposez et questionnez ; chaque modification préserve l'objectif métier original, et toute réécriture qui nécessiterait des décisions de périmètre devient une question, pas un choix unilatéral. Le risque d'invention est aigu ici : une US existante semble souvent « presque prête » et la tentation de la terminer en silence est forte. Une US avec des lacunes visibles est bien plus précieuse pour l'affinage qu'une histoire « complète » avec des règles que le PO n'a jamais écrites.

US : $ARGUMENTS

Avant de commencer

Lire docs/agents/refinement.md dans l'espace de travail : il définit le mode de fonctionnement (avec ou sans code), la langue (en-US ou pt-BR par défaut en-US), les slugs et les chemins de publication. Si manquant, demander à l'utilisateur d'exécuter /configure-refinement et s'arrêter. Tout dialogue d'examen, questions et artefact synthétisé suivent la langue configurée de l'espace de travail.

Étapes

1. Charger. Lire l'US (chemin de fichier, ID de tracker ou texte collé), CONTEXT.md, les ADR du domaine, et invoquer l'outil Skill pour requirements-rigor. Si .scratch/<slug>/ existe déjà pour cette US, inspecter son contenu : une session précédente a peut-être résolu des questions, que vous ne devez pas répéter. Le slug suit les conventions de docs/agents/refinement.md. Si docs/adr/ ou .scratch/ sont absents, continuer sans avertissement. Terminé quand : vous pouvez classer l'US en une seule ligne : ANALYSABLE (a un récit et des critères, même imparfaits), SQUELETTE (titre uniquement, ou récit sans critères), ou PAS UNE US (épopée déguisée, tâche technique, exigence non fonctionnelle autonome).

2. Trier. PAS UNE US : indiquer de quel type d'artefact il s'agit réellement, fournir une justification de 2 à 3 lignes, et recommander le traitement approprié : épopée déguisée, décomposer avec /requirements-discovery ; tâche technique, reclassifier comme tâche ; exigence non fonctionnelle autonome, déplacer vers la liste des exigences non fonctionnelles. Si l'élément se trouve dans l'espace de travail, ajouter Statut : pas une US (ou Status: não é US) et la justification sous le titre pour laisser une trace. S'arrêter ici. SQUELETTE : continuer, et le premier tour d'examen demande les scénarios manquants plutôt que de les inventer. Terminé quand : la classification est indiquée en une seule ligne et, dans le cas PAS UNE US, la justification et le traitement sont également fournis.

3. Auditer en silence. Appliquer les règles de requirements-rigor au récit et aux critères : INVEST, Gherkin, anti-patrons (lire ANTI-PATTERNS.md séparément), termes qui déclenchent toujours des questions. Chaque constat devient une question candidate ou une correction qui préserve le comportement exact décrit : convertir la prose en Gherkin, déplacer la Définition de Fin (DoD) hors des critères, déplacer les tâches d'implémentation dans les notes. Terminé quand : chaque critère a une destination (conserver, convertir, déplacer, questionner) et chaque terme ambigu a une question candidate.

4. Rechercher des faits avant de demander. Les faits sont votre responsabilité, jamais celle du PO. Pour chaque question candidate, rechercher dans les sources de l'espace de travail : glossaire, histoires précédentes dans .scratch/, documents joints par le PO. En mode code, envoyer un sous-agent pour fouiller le code source pour ce que l'US affirme ou suppose : la règle existe-t-elle ? la limite est-elle implémentée ? la fonction d'intégration existe-t-elle ? Un fait trouvé devient une réponse recommandée citant la source. En mode sans code, la recherche est limitée aux fichiers de l'espace de travail sans sous-agents ; si rien n'est trouvé, le mentionner en une seule ligne en haut du round 1. Terminé quand : chaque question candidate est marquée comme répondue par une source (avec citation) ou ouverte pour le PO.

5. Examiner. Invoquer l'outil Skill pour socratic-examination et suivre sa discipline : rounds, frontière, réponses recommandées avec citations ou « aucune recommandation », faits vôtres et décisions du PO, glossaire mis à jour immédiatement. Le round 1 s'ouvre avec un triage d'une ligne, marque les questions qui bloquent le verdict, et se termine par des notes sur les critères déplacés sans question et les questions routées vers l'équipe d'ingénierie. Les questions architecturales n'entrent pas dans les rounds avec le PO : les router directement vers des questions ouvertes pour l'équipe d'ingénierie. Les questions auxquelles le PO ne peut pas répondre reçoivent [À CONFIRMER : qui] (ou [A CONFIRMAR: quem]) et quittent la frontière. Terminé quand : la frontière est vide, ou le PO demande de clôturer avec les informations actuelles.

6. Synthétiser. Écrire l'US affinée en suivant TEMPLATE.md, avec les lacunes restantes visibles sous forme de marqueurs. Exécuter l'auto-audit Gherkin. Rendre le verdict : PRÊT, AFFINER avec les numéros de questions qui le débloquent, ou BLOQUÉ avec justification. Si [DÉCOMPOSER] est présent, inclure la proposition de décomposition : récit pour chaque partie et mappage des critères originaux. Terminé quand : le fichier existe au chemin défini par docs/agents/refinement.md, avec Statut : correspondant au verdict et la clause de non-responsabilité finale présente.

7. Router les éléments ouverts. Pour chaque destinataire en dehors de la session avec [À CONFIRMER], écrire un questionnaire suivant QUESTIONNAIRE.md dans requirements-rigor, à côté de l'US affinée, et lier le fichier depuis la section des questions ouvertes. Terminé quand : aucun [À CONFIRMER] ne reste sans destinataire ou questionnaire.

8. Rapporter. Informer l'utilisateur de manière concise : verdict, où l'US a été publiée, quelles questions la débloquent et les questionnaires générés.

Exemple de round

Pour l'US « En tant qu'utilisateur, je souhaite exporter des rapports en PDF pour faciliter le partage. CR1 : le bouton d'exportation doit fonctionner correctement. CR2 : créer un service de génération de PDF sur le backend. CR3 : le PDF doit s'ouvrir rapidement. CR4 : code révisé et tests réussis. », dans un espace de travail sans code dont le glossaire liste l'analyste opérationnel et le gestionnaire de comptes comme consommateurs de rapports, le premier round ressemble à :

❓ Q1. Qui exporte ? (bloquant) Le récit indique « utilisateur ». Le glossaire liste l'analyste opérationnel et le gestionnaire de comptes comme rôles consommant des rapports. Quel rôle exporte, ou les deux ? Recommandation : analyste opérationnel [INFÉRENCE : rôle associé aux « rapports opérationnels » dans le glossaire]. Sans cela, les permissions restent indéfinies et le récit échoue à INVEST.

❓ Q2. Que signifie « s'ouvrir rapidement » ? (bloquant) CR3 est non testable et admet deux lectures : temps entre le déclenchement de l'exportation et le début du téléchargement, ou temps pour que le fichier s'ouvre dans un lecteur. Laquelle est visée, et quel est le temps maximum en secondes ? Recommandation : aucune recommandation : le texte source ne fournit aucune base d'interprétation ou chiffres de SLA. Si aucune attente n'existe, enregistrer [À CONFIRMER : PO] et continuer.

❓ Q3. Cas limites La source sous-entend des rapports vides et des rapports à grand volume [INFÉRENCE : les rapports varient en volume]. Lesquels sont pertinents pour cette livraison ? Recommandation : inclure les deux comme scénarios [INFÉRENCE : découlent du texte source]. Le comportement spécifique pour chacun est votre décision : aucune recommandation. Le volume maximum dépend de Q2.

CR2 et CR4 ne déclenchent pas de questions : CR2 est une tâche d'implémentation dont le comportement activé est couvert par CR1, déplacement dans les notes ; CR4 est la Définition de Fin de l'équipe et est supprimé des critères. Les deux apparaissent dans la section d'audit de l'artefact final comme déplacés, pas supprimés.

Avis final

Chaque artefact publié se conclut par :

⚠️ Ce résultat est une préparation pour l'affinage, pas un remplacement. Les décisions sur le périmètre, la valeur et la priorité appartiennent strictement au PO et à l'équipe.