RafaelFerSilva/refinement-agent-skills

Découverte

Convertissez les contributions non structurées des parties prenantes en exigences traçables grâce à un examen socratique. Vous n'êtes pas un transcripteur : capturez ce qui a été dit et ce qui a été implicite, signalez les ambiguïtés et produisez des stories candidates que /refine-story transportera jusqu'au sprint planning. Ce que la contribution ne supporte pas n'entre pas ; ce qu'elle suggère entre comme une inférence fondée ; ce qu'elle laisse ouvert devient une question.

Entrée : $ARGUMENTS

Avant de commencer

Lisez docs/agents/refinement.md dans l'espace de travail : il définit le mode de fonctionnement, la langue (en-US ou pt-BR, par défaut en-US) et les chemins de publication. S'il est manquant, demandez /configure-refinement et arrêtez-vous. Si l'argument est une spécification avec Status: open map (ou Status: mapa aberto), passez directement à « Reprendre la carte de décision ». Si l'entrée provient de /meeting-minutes, elle sépare déjà les faits énoncés des présomptions : traitez les accords présumés comme non confirmés. L'examen et les spécifications générées suivent la langue configurée de l'espace de travail.

Étapes

1. Charger et trier. Lisez l'entrée, CONTEXT.md, et invoquez l'outil Skill pour requirements-rigor. Recherchez les anti-patrons (lisez ANTI-PATTERNS.md dans requirements-rigor séparément) et les termes qui déclenchent toujours des questions : cette analyse fonde le tri. Classez en comptant les extraits, pas le volume de texte : UTILISABLE (chaque extrait structure une exigence), PARTIELLEMENT UTILISABLE (au moins un extrait structure une exigence et au moins un ne le fait pas), INUTILISABLE (aucun extrait ne structure une exigence). INUTILISABLE : indiquez-le avec une justification extrait par extrait, listez 3 à 5 questions minimales avec les destinataires (quiconque a fourni l'entrée, à moins qu'un rôle métier dans le glossaire soit identifiable), rédigez un questionnaire suivant QUESTIONNAIRE.md dans requirements-rigor, informez l'utilisateur que /requirements-discovery sera relancé avec les réponses, et arrêtez-vous sans publier d'autres artefacts ; des stories de remplissage n'aident personne. PARTIEL : procédez, et l'artefact final commence par une liste des extraits inutilisés et de ce qui manque dans chacun. Terminé quand : la classification est énoncée sur une seule ligne, suivie d'une justification extrait par extrait lorsque ce n'est pas UTILISABLE.

2. Cartographie en largeur d'abord. Avant de générer une story, scannez l'intégralité de l'entrée : domaines métier avec indices de confiance (Élevé, Moyen, Faible ; Faible marque les domaines où la découverte nécessite une conversation de suivi), parties prenantes avec type (métier, technique, utilisateur final) et ce que chacune défend, épopées avec complexité S, M, L ou XL justifiée en une seule ligne ; les extraits sans listes fermées ou critères mesurables ne deviennent pas encore des épopées, restant en traitement partiel jusqu'à ce que l'examen les dimensionne. Lorsque l'entrée est de seconde main, le preneur de notes entre dans le tableau des parties prenantes avec le type « source ». Deux voix en positions opposées sur la même exigence : ajoutez [CONFLIT], en enregistrant les deux positions sans résoudre unilatéralement. Une exigence énoncée par une seule voix reçoit [VALIDER AVEC L'ÉQUIPE] lorsque la confirmation est critique : besoins de rôle non satisfaits, décisions de périmètre prises par des non-décideurs ; ne marquez pas tout lorsque deux voix abordent des sujets disjoints. Les besoins métier et les contraintes techniques proviennent de différentes parties prenantes et ont un poids différent : distinguez-les. Terminé quand : chaque extrait d'entrée est mappé à un domaine et une épopée, ou listé comme inexploité.

3. Rechercher des faits avant de demander. Vérifiez le glossaire, les stories précédentes dans .scratch/, les documents de l'espace de travail, et en mode code, la base de code : l'intégration mentionnée existe-t-elle déjà ? Le seuil est-il déjà implémenté ? Un fait trouvé devient une réponse recommandée avec source citée. En mode sans code, la recherche est limitée aux fichiers de l'espace de travail sans sous-agents ; si rien n'est trouvé, indiquez-le sur une seule ligne en haut du tour 1. Terminé quand : chaque question candidate est marquée comme répondue par une source ou ouverte.

4. Décider de la taille du périmètre. Invoquez l'outil Skill pour socratic-examination et examinez en largeur d'abord : le résultat cible (ce que cette découverte livre), les limites du périmètre, les conflits et les facteurs affectant la taille de l'épopée. Les SLA, canaux et cas limites représentent la profondeur et sont différés à l'étape 5. Si à la fin de ce tour la frontière tient dans une seule session, passez à l'étape 5. S'il reste un brouillard substantiel (décisions anticipées mais pas encore formulables car elles dépendent de réponses en attente), ouvrez la carte : publiez la spécification suivant TEMPLATE.md avec Status: open map, une décision en attente par fichier dans issues/NN-decision-<slug>.md pour chaque question formulable, en marquant Blocked by: lorsque dépendante d'une autre, et le brouillard non formulable dans « Non encore spécifié ». La distinction entre une décision et un brouillard est de savoir si vous pouvez formuler la question avec précision maintenant, pas si vous pouvez y répondre. Cartographier le brouillard est l'objectif d'une session : arrêtez-vous et informez l'utilisateur que /requirements-discovery <spec-path> résout une décision par session. Terminé quand : soit la frontière des questions tient dans une seule session, soit la spécification avec une carte ouverte et des fichiers de décision en attente existe.

5. Examiner. Continuez les tours de socratic-examination en profondeur, épopée par épopée : rôles, capacités, résultats, cas limites suggérés par l'entrée, dépendances. Les termes du domaine résolus sont ajoutés immédiatement à CONTEXT.md. Un fait qu'aucun participant ne connaît reçoit [À CONFIRMER : qui] (ou [A CONFIRMAR: quem]) et laisse la frontière. Terminé quand : la frontière est vide, ou l'utilisateur demande la clôture.

6. Synthétiser. Rédigez la spécification de découverte suivant TEMPLATE.md et une story candidate par fichier suivant skills/refine-story/TEMPLATE.md, avec Status: candidate (ou Status: candidata) et un scorecard INVEST préliminaire. Une story qui échoue à INVEST ne devient pas une carte propre : elle reste candidate avec [INVEST-ÉCHEC] et des conseils de résolution. Incluez les dépendances non déclarées : intégrations, services externes et décisions architecturales nécessaires à l'implémentabilité des stories, chacune associée à la story bloquée et à l'action requise. Chaque ligne des stories candidates correspond à l'entrée ou à une [INFÉRENCE : base] valide ; les ajouts non fondés sont de l'orfèvrerie et doivent être supprimés. Terminé quand : la spécification et les stories candidates existent au chemin défini dans docs/agents/refinement.md, avec la clause de non-responsabilité finale.

7. Acheminer les éléments ouverts. Ouvrez les éléments [À CONFIRMER] avec des destinataires en dehors de la session : rédigez un questionnaire par destinataire suivant QUESTIONNAIRE.md dans requirements-rigor, parallèlement à la spécification. Terminé quand : aucune question ouverte ne reste sans destinataire ou questionnaire.

8. Rapporter. Épopées créées, nombre de stories candidates, conflits ouverts et prochaines étapes : /refine-story par story, ou /requirements-discovery <spec-path> si la carte est ouverte.

Reprendre la carte de décision

Lorsque l'argument est une spécification avec Status: open map :

1. Lisez la spécification complète et les décisions en attente dans issues/. Une décision est débloquée lorsqu'elle est ouverte et que toutes les décisions dans Blocked by: sont résolues. Terminé quand : vous savez quelles décisions sont débloquées.
2. Sélectionnez la décision : nommée par l'utilisateur, ou la première débloquée par numéro. Marquez Status: in examination dans le fichier avant de commencer, empêchant les sessions concurrentes de la sélectionner. Terminé quand : le statut du fichier est mis à jour.
3. Résolvez-la avec socratic-examination, une décision par session. Les décisions de type recherche sont résolues en lisant des sources externes avec des citations, sans tours d'examen. Enregistrez la réponse directement dans le fichier sous ## Answer, marquez Status: resolved, et ajoutez une ligne avec le résumé et le chemin dans la section « Décisions d'examen » de la spécification. Terminé quand : la décision est résolue et liée depuis la spécification.
4. La réponse peut dissiper le brouillard environnant : les éléments nouvellement formulables quittent « Non encore spécifié » et deviennent de nouvelles décisions en attente ; les éléments hors périmètre passent à « Hors de portée ». Toute décision invalidée par la réponse est fermée avec une justification d'une ligne. Terminé quand : aucune décision en attente ne contredit la réponse et le brouillard est réévalué.
5. Sans décisions en attente ouvertes : mettez à jour la spécification en Status: in progress et passez à l'étape 5 des étapes principales, dans la même session si le contexte le permet, sinon dans la session suivante en utilisant la même commande. Terminé quand : la spécification quitte le statut de carte ouverte, ou vous rapportez combien de décisions restent.

Format de décision en attente :

# Décision NN : <question en une phrase>

Status: <open | in examination | resolved | closed>
Blocked by: <NN, NN ou none>
Type: <examination | research>

## Question

<ce qui doit être décidé et pourquoi cela bloque la progression>

## Answer

<lors de la résolution : décision, qui a décidé, date>

Avis final

⚠️ Cette sortie est un projet analytique. Elle nécessite une revue humaine avant d'entrer dans un sprint. Validez : la faisabilité technique, la conformité et les dépendances non cartographiées.