Rédiger et entretenir des compétences en gestion de produit qui enseignent à bien juger

## Garder les raisons et les exemples qui apprennent à l’utilisateur à bien juger ### Servir les deux publics Une compétence en gestion de produit doit aider un praticien à accomplir un travail utile et à progresser dans son métier. Concevez chaque compétence à la fois pour la personne qui développe son discernement et pour l'agent qui exécute le flux de travail. N'optimisez pas l'expérience d'un public au détriment de l'autre. Rendez le raisonnement qui sous-tend le flux de travail suffisamment visible pour que les recommandations soient fiables, explicables et transposables. L'utilisateur doit comprendre pourquoi une approche fonctionne, et non simplement recevoir un livrable terminé. ### Protéger la structure d'apprentissage - Ne raccourcissez pas les explications si cela supprime le raisonnement nécessaire à des décisions éclairées. - Conservez les anti-modèles explicites, car ils apprennent aux utilisateurs ce qu'ils doivent reconnaître et éviter dans des situations réelles. - Utilisez des exemples qui montrent le processus de raisonnement, et pas seulement le résultat final. - Définissez les termes spécialisés dès leur première apparition et explicitez les compromis. - Maintenez un flux de travail pratique et exploitable par un agent sans lui retirer sa dimension de coaching. Lorsque vous améliorez l'efficacité, éliminez les répétitions, le remplissage et le contexte secondaire avant de retirer des enseignements, des exemples ou des modes de défaillance. S'il n'est pas clair si un passage constitue un soutien pédagogique ou un contenu superflu, conservez-le jusqu'à ce que sa fonction soit comprise. ### Démontrer la qualité dans différents contextes Incluez au moins un exemple concret montrant comment des preuves mènent à une décision. Pour une compétence pleinement aboutie, ajoutez un modèle réutilisable et des exemples détaillés provenant de deux contextes commerciaux sensiblement différents, comme un service logiciel et une entreprise physique ou opérationnelle. Utilisez des organisations et des données fictives. ## Donner à chaque compétence son propre dossier et ne jamais modifier à la main les listes générées ### Séparer les sources canoniques des résultats dérivés Conservez chaque compétence dans son propre dossier, nommé de manière cohérente, avec un seul document canonique et tous les éléments ou scripts d'accompagnement qui lui sont propres. Stockez les commandes d'orchestration réutilisables séparément des compétences individuelles. Maintenez la recherche, la documentation utilisateur, les applications de prévisualisation et les livrables de publication dans des espaces distincts dont la responsabilité est clairement définie. Considérez les catalogues générés, les index, les copies de paquets et les lots de distribution comme des artefacts dérivés. Régénérez-les à partir des sources canoniques au lieu de les modifier directement. Utilisez la notation kebab-case en minuscules pour les noms des dossiers de compétences et synchronisez le nom du dossier avec le nom déclaré de la compétence. Préservez des chemins stables dans la mesure du possible ; ne renommez une compétence qu'en cas de nécessité, puis mettez à jour chaque référence. ### Respecter les limites de responsabilité Avant de modifier le contenu, confirmez quel dépôt ou espace de travail en est responsable. Une bibliothèque partagée, un manuel propre à un produit et un dépôt de distribution peuvent se référer les uns aux autres tout en ayant des sources de référence différentes. Travaillez dans l'emplacement responsable et traitez les autres comme des références en lecture seule, sauf si la tâche modifie explicitement cette limite. Ne déduisez pas la structure du seul nom familier d'un répertoire. Avant de prendre des décisions structurelles, consultez les définitions, les règles de contribution, les scripts et les exemples existants propres au dépôt. ### Trouver la capacité la plus précise Avant d'improviser des conseils en gestion de produit, examinez les compétences disponibles et choisissez celle qui correspond le plus précisément au besoin. Les domaines courants comprennent la découverte, Jobs to Be Done, les personas, la stratégie produit, la priorisation, les feuilles de route, les documents d'exigences, les récits utilisateur, les critères d'acceptation, le travail sur des produits d'intelligence artificielle, les flux de travail d'agents et l'alignement des parties prenantes. Traitez-les comme des flux de travail de coaching et de production de livrables, et non comme des tâches générales d'ingénierie logicielle. ## Mettre des exemples et des erreurs courantes dans chaque compétence et poser une question à la fois ### Utiliser un contrat documentaire cohérent Donnez à chaque compétence une séquence claire, par exemple Objectif, Entrée, Concepts Clés, Application, Exemples, Pièges Courants et Références. Incluez dans le frontmatter les champs name, description et type. Lorsque les plateformes cibles imposent ces limites, maintenez name dans une limite de 64 caractères et description dans une limite de 200 caractères. Utilisez des titres Markdown clairs et des paragraphes courts. Ajoutez des identifiants de langage aux blocs de code délimités. Rédigez de manière concise et affirmée, sans sacrifier le raisonnement, les conditions ou les exemples nécessaires. ### Faire de l'entrée une invitation, pas un obstacle La section Entrée doit expliquer en termes simples ce que l'utilisateur peut fournir et inclure un exemple d'appel. Considérez les informations fournies dans la demande comme des réponses déjà données. Autorisez une entrée initiale partielle ou inexistante. Expliquez comment le déroulement guidé recueillera les informations manquantes plutôt que de bloquer l'utilisateur. Évitez les espaces réservés propres à un environnement d'exécution ou les syntaxes de modèles qui apparaîtraient littéralement dans des environnements non pris en charge. ### Concevoir délibérément les flux interactifs Pour une compétence interactive : - Posez une seule question à la fois ou utilisez de petits groupes cohérents. - Laissez chaque réponse façonner la question suivante. - Proposez des recommandations numérotées, adaptées au contexte, pour les prochaines étapes. - Autorisez aussi bien la sélection par numéro qu'une saisie personnalisée. - Adaptez le flux de travail lorsque les choix de l'utilisateur modifient le parcours pertinent. Rendez la compétence autonome et utilisable par un agent sans hypothèses cachées. Incluez au moins un anti-modèle explicite et expliquez pourquoi il échoue. ## Vérifier les compétences et leurs liens avec les outils de la bibliothèque avant de les partager ### Utiliser le parcours de validation propre à la bibliothèque Privilégiez les outils documentés du dépôt pour la découverte, la validation, l'empaquetage et les tests de l'ensemble de la bibliothèque plutôt que les vérifications improvisées. Utilisez la recherche de fichiers et des recherches de références ciblées pour vérifier l'emplacement des compétences et les renvois avant de soumettre des modifications. Vérifiez que les chemins canoniques des compétences peuvent être résolus, que les métadonnées sont valides, que les sections obligatoires sont présentes, que les exemples et les références sont exacts et que les liens restent cohérents. Lorsque les tests automatisés ne sont pas disponibles, effectuez ces vérifications manuellement plutôt que d'affirmer un succès non vérifié. Exécutez le générateur de paquets et le générateur de catalogues par leurs points d'entrée maintenus. Si une application de prévisualisation a changé, utilisez le parcours de prévisualisation local pertinent et vérifiez sa documentation. ### Préserver la compatibilité et la sécurité de l'automatisation Respectez les exigences d'empaquetage propres à chaque plateforme, notamment la casse exacte des noms de fichiers lorsqu'elle est requise. Maintenez les scripts d'accompagnement déterministes, documentés et dépourvus d'accès au réseau, sauf si le flux de travail l'exige et l'encadre explicitement. Vérifiez la sécurité des scripts et du contenu empaqueté avant de les partager ou de les exécuter. Ne retirez pas les fichiers gérés de place de marché, d'extension ou de compatibilité simplement parce qu'ils semblent sans rapport. Ne modifiez pas les artefacts de publication générés pour éviter de corriger leur source canonique. ### Vérifier la véritable source de référence Avant de modifier une catégorie, un type de compétence ou une structure de paquet, fondez la décision sur les critères locaux et sur la compétence canonique concernée. Privilégiez les preuves fournies par les validateurs maintenus et les outils du dépôt plutôt que les conventions personnelles. Si le travail demandé relève d'un autre dépôt, interrompez toute écriture à la limite actuelle et dirigez la modification vers la source responsable. Les documents de référence peuvent éclairer le travail sans pour autant devenir la cible de la modification. ## Faire de petits changements et suivre une liste de contrôle avant de publier ### Préparer des contributions faciles à examiner Maintenez les modifications petites, faciles à entretenir et limitées à l'objectif déclaré. Utilisez des objets de commit clairs et formulés à l'impératif. Une demande d'examen doit résumer la modification, fournir des liens vers les problèmes concernés, identifier le type de compétence et signaler les changements significatifs de compatibilité ou de comportement. Lorsque vous ajoutez ou renommez une compétence, mettez à jour les entrées de catalogue, les décomptes, les tableaux, les chemins et les renvois. Avant la publication, vérifiez que toutes les références peuvent être résolues. ### Appliquer une liste de contrôle complète pour la publication - Validez les dossiers canoniques des compétences et les métadonnées. - Reconstruisez à partir de la source les paquets téléchargeables et les catalogues générés. - Confirmez que les exemples, les références et les liens de navigation restent exacts. - Vérifiez la syntaxe du frontmatter et toutes les copies de paquets propres à une plateforme. - Mettez à jour la documentation de l'interface et les notes de publication lorsqu'une application de prévisualisation change. - Vérifiez qu'aucun artefact généré, fichier sans rapport ou remplacement général involontaire n'a intégré la modification. ### Utiliser les résultats pédagogiques comme critère final Une compétence prête à être publiée est pédagogique, exploitable par un agent, autonome et pratique. Elle comprend un raisonnement, au moins un exemple détaillé, un anti-modèle explicite, des termes spécialisés définis et des compromis visibles. Une compétence pleinement aboutie comprend également un modèle réutilisable et des exemples issus de domaines contrastés. Ne retirez pas les explications, les anti-modèles ou les exemples dans le seul but de réduire la longueur. N'approuvez la publication que lorsque la compétence produit un résultat utile, renforce le discernement de l'utilisateur et reste facile à entretenir dans tous les environnements pris en charge.