brmdias/best-practice

Compétence Documentation de Bonne Pratique

Automatise l'ensemble du flux de documentation des bonnes pratiques dans la base de connaissances TAM, réduisant le travail manuel de 2 à 4 heures à 10-15 minutes.

Utilisation

/best-practice <nom-du-sujet>
/bp <nom-du-sujet>

Exemples :

• /bp webhook-timeout-patterns
• /best-practice runner-disk-management
• /bp ansible-integration-patterns

Ce que fait cette compétence

Exécute le flux complet de documentation des bonnes pratiques :

1. Valider et vérifier l'existant – Éviter les doublons, gérer les mises à jour
2. Rechercher dans la base de connaissances – Trouver des investigations similaires, des bonnes pratiques, des exemples clients
3. Rechercher dans la documentation – Trouver des conseils officiels et des informations de version
4. Rechercher dans le code produit – Vérifier les détails techniques et les valeurs par défaut (si pertinent)
5. Rechercher sur GitHub – Trouver des problèmes communautaires, des bugs et des demandes de fonctionnalités
6. Rechercher dans Jira – Localiser les tickets de développement internes et les versions de correction
7. Recherche communautaire – WebFetch des sources externes si nécessaire (optionnel)
8. Synthétiser les résultats – Présenter un résumé de recherche pour confirmation de l'utilisateur
9. Générer le document – Créer la bonne pratique en suivant la structure TEMPLATE.md
10. Mettre à jour INDEX.md – Ajouter aux catégories, au tableau alphabétique et à la référence rapide
11. Signaler l'achèvement – Résumé complet avec les prochaines étapes

Instructions

Lorsque cette compétence est invoquée, suivez ces étapes :

Étape 1 : Analyser les arguments et valider

Extraire le nom du sujet des arguments :

• Requis : nom du sujet (ex. "webhook-timeout-patterns")
• Convertir en kebab-case si ce n'est pas déjà le cas
• Si le sujet dépasse 80 caractères, avertir : "Le sujet semble large. Envisagez de le diviser ?"

Si aucun sujet n'est fourni :

• Erreur : "Utilisation : /best-practice "
• Montrer les exemples

Étape 2 : Vérifier l'existence d'une bonne pratique

Rechercher les bonnes pratiques existantes avec des noms similaires :

Glob pattern="*${keywords}*" path="best-practices/"

Logique de décision :

• Correspondance exacte : Demander à l'utilisateur : "Une bonne pratique existe à <fichier>. (1) Mettre à jour l'existante, (2) Créer une nouvelle avec un axe différent, (3) Annuler ?"
• Correspondances partielles : Les lister, demander : "Similaires trouvées : <fichiers>. (1) Mettre à jour l'une d'elles, (2) Créer une nouvelle, (3) Annuler ?"
• Aucune correspondance : Procéder à la création

Si l'utilisateur choisit la mise à jour, noter le nom du fichier pour une modification ultérieure (Edit au lieu de Write).

Étape 3 : Rechercher dans la base de connaissances

Extraire les mots-clés de recherche du nom du sujet (supprimer les traits d'union, diviser en termes).

Rechercher dans les bonnes pratiques :

Grep pattern="<mots-clés>" path="best-practices/" output_mode="content" -C 3 head_limit=50

Rechercher dans les investigations :

Grep pattern="<mots-clés>" path="investigations/" output_mode="content" -C 3 head_limit=50

Rechercher dans les profils clients (si pertinent) :

Grep pattern="<mots-clés>" path="customers/" output_mode="files_with_matches"

Si des profils clients sont trouvés, les lire pour recueillir le contexte.

Collecter et noter :

• Bonnes pratiques connexes (pour la section "Bonnes pratiques connexes")
• Exemples d'investigations (pour la section "Exemples concrets")
• Tags courants des documents similaires (pour les métadonnées)
• Contexte client le cas échéant

Étape 4 : Rechercher dans la documentation officielle

Grep pattern="<mots-clés>" path="repositories/docs/" output_mode="content" -C 2 head_limit=30

Collecter et noter :

• Conseils et recommandations officiels
• Informations spécifiques à une version
• Références et options de configuration
• Limites ou mises en garde connues

Étape 5 : Rechercher dans le code produit (conditionnelle)

Quand rechercher :

• Le sujet implique un comportement spécifique d'une fonctionnalité
• Besoin de valeurs de configuration par défaut
• Comprendre les caractéristiques de performance
• Vérifier les contraintes techniques

Grep pattern="<composant|classe>" path="repositories/rundeckpro/" output_mode="content" head_limit=30

Collecter et noter :

• Valeurs de configuration par défaut
• Détails d'implémentation et comportement
• Contraintes ou limites techniques
• Logique spécifique à une version

Étape 6 : Rechercher dans les issues GitHub (via le connecteur Runlayer)

Interroger GitHub via le connecteur Runlayer – l'outil CLI gh n'est pas disponible dans cet environnement. Appelez search_tools pour localiser l'outil de recherche d'issues GitHub, puis execute_tool pour rechercher dans rundeck/rundeck et rundeckpro/rundeckpro les <mots-clés> parmi les issues ouvertes et fermées. N'utilisez pas de commande shell avec gh.

Collecter et noter :

• Problèmes ou bugs connus
• Demandes de fonctionnalités et retours de la communauté
• Solutions de contournement et solutions communautaires
• Numéros d'issues pour citation

Si le connecteur GitHub est indisponible, notez-le et continuez.

Étape 7 : Rechercher dans le projet Jira RUN (via le connecteur Runlayer)

Interroger Jira via le connecteur Runlayer. Appelez search_tools pour localiser l'outil de recherche d'issues Jira, puis execute_tool avec le tool_name exact et les arguments retournés. N'appelez pas directement les outils mcp__atlassian__*. Utilisez des paramètres équivalents à :

jql: "project=RUN AND (summary ~ \"<mots-clés>\" OR description ~ \"<mots-clés>\") ORDER BY updated DESC"
maxResults: 15

Collecter et noter :

• Tickets de développement internes
• Versions de correction et informations de publication
• Statut et contexte de développement
• Clés Jira pour citation (RUN-XXXX)

Gestion des erreurs : Si le connecteur Jira est indisponible, notez "Recherche Jira indisponible" et continuez.

Étape 8 : Recherche communautaire (optionnelle/si nécessaire)

Déclencheur :

• Moins de 3 sources pertinentes trouvées aux étapes 3 à 7
• Modèle nouveau ou émergent peu documenté
• L'utilisateur indique qu'une recherche plus large est nécessaire

WebFetch avec paramètres :
  url: "https://groups.google.com/g/rundeck-discuss/search?q=<mots-clés>"
  prompt: "Trouver des discussions sur <sujet>. Extraire : problèmes signalés, solutions proposées, modèles recommandés, problèmes courants"

Collecter et noter :

• Solutions et modèles communautaires
• Pièges et problèmes courants
• Variations d'implémentation
• Important : Signaler les affirmations non vérifiées, les vérifier par rapport à la documentation officielle

Étape 9 : Synthétiser les résultats et obtenir la confirmation de l'utilisateur

Analyser tous les résultats de recherche :

1. Identifier les modèles entre les sources
2. Déterminer la recommandation : Approche principale avec justification
3. Identifier les alternatives : Autres approches et pourquoi la principale est préférée
4. Extraire l'implémentation : Pas à pas avec des exemples de code
5. Documenter les avantages et les compromis
6. Sélectionner les métadonnées :
   • Domaine produit : Déterminer parmi ces catégories :
     • Conception et orchestration des jobs
     • Gestion et ciblage des nœuds
     • Sécurité et contrôle d'accès
     • Performance et mise à l'échelle
     • Intégrations et webhooks
     • Architecture et déploiement
     • Documentation et maintenance
   • Applicable à partir de la version : D'après Jira/docs (être spécifique comme "Rundeck 5.6.0+" ou prudent "Toutes les versions")
   • Tags : Utiliser la taxonomie existante des BP similaires (analyser les tags trouvés à l'étape 3), 3 à 8 tags maximum

Présenter le résumé de recherche à l'utilisateur :

# Résumé de recherche : <nom-du-sujet>

## Sources trouvées
- Base de connaissances : X investigations, Y bonnes pratiques
- Documentation : N pages
- GitHub : P issues
- Jira : Q tickets
- Communauté : [si recherché]

## Approche recommandée
[Résumé en 1-2 paragraphes de la recommandation principale basée sur la recherche]

## Modèles clés identifiés
- [Modèle 1 issu de la recherche]
- [Modèle 2 issu de la recherche]
- [Modèle 3 issu de la recherche]

## Métadonnées proposées
- **Domaine produit :** [catégorie déterminée]
- **Applicable à partir de la version :** [version issue de la recherche]
- **Tags :** #tag1 #tag2 #tag3 [d'après les BP similaires]

## Contrôle qualité
- ✓ [X] sources trouvées (minimum 4 recommandé)
- ✓ [Y] exemples de code/configuration disponibles
- ✓ [Z] exemples concrets trouvés

Prêt à générer le document ?

Attendre la confirmation de l'utilisateur. L'utilisateur peut :

• Confirmer et continuer
• Demander des modifications des métadonnées ou de l'approche
• Demander des recherches supplémentaires
• Annuler le flux

Ne PAS passer à la génération sans confirmation de l'utilisateur.

Étape 10 : Générer le document de bonne pratique

Une fois que l'utilisateur confirme, générer le document :

1. Lire le modèle pour référence :

Read file_path="best-practices/TEMPLATE.md"

2. Remplir toutes les sections avec le contenu recherché :

En-tête (lignes 1-6) :

# [Nom du sujet en Cas de Titre]

**Dernière mise à jour :** 2026-04-20
**Domaine produit :** [de l'étape 9]
**Applicable à partir de la version :** [de l'étape 9]
**Tags :** #tag1 #tag2 #tag3 [de l'étape 9]

---

Cas d'utilisation / Scénario :

• Décrire quand quelqu'un en a besoin (d'après les investigations + documentation)
• Quel problème cela résout-il ?
• À quels scénarios cela s'applique-t-il ?

Recommandation :

• Conseils clairs et exploitables (le "quoi faire")
• Approche principale issue de la synthèse
• Peut inclure un tableau si plusieurs options

Implémentation :

• Procédure pas à pas
• Plusieurs modèles si applicable (Modèle 1, Modèle 2, etc.)
• Exemples de code issus de la documentation et de la recherche de code

# Inclure des exemples concrets YAML/config
# Utiliser les extraits de code trouvés dans la recherche

Pourquoi cela fonctionne :

• Explication technique issue de la recherche de code + documentation
• Principes ou mécanismes sous-jacents
• Pourquoi cette approche est efficace

Avantages :

• Liste numérotée des résultats de recherche
• Avantages concrets (performance, sécurité, maintenabilité, etc.)
• Quantifier si possible

Compromis / Mises en garde :

• Limites identifiées dans la recherche
• Considérations de performance
• Situations où cela pourrait ne pas s'appliquer
• ⚠️ Signaler les informations contradictoires si trouvées

Alternatives envisagées :

• Autres approches trouvées dans la recherche
• Pourquoi l'approche recommandée est préférée
• Quand les alternatives pourraient être meilleures

Exemples concrets :

• Liens vers les investigations : [Client/Cas](../investigations/YYYY-MM-DD-description.md)
• Si aucun : "Aucune investigation documentée pour le moment. Cette bonne pratique est basée sur [documentation officielle/analyse de code/modèles communautaires]."

Bonnes pratiques connexes :

• Liens vers les documents connexes de la recherche dans la base de connaissances
• Format : [Titre](./nom-du-fichier.md) - Brève description

Documentation officielle :

• Liens vers les fichiers du dépôt de documentation
• Issues GitHub par numéro
• Tickets Jira par clé
• Liens vers le site officiel

3. Contrôles qualité avant l'écriture :

• ✓ Les 4 champs de métadonnées remplis
• ✓ 3 à 8 tags de la taxonomie existante
• ✓ Toutes les sections du modèle présentes
• ✓ Au moins 1 exemple de code/configuration
• ✓ Au moins 2 sources citées
• ✓ Format markdown correct

4. Écrire le document :

Si création nouvelle :

Write file_path="best-practices/<nom-kebab-du-sujet>.md" content="<contenu-généré>"

Si mise à jour d'un existant (de l'étape 2) :

Edit file_path="best-practices/<nom-du-fichier-existant>.md"

Mettre à jour les sections pertinentes tout en préservant la structure.

Étape 11 : Mettre à jour INDEX.md

1. Lire l'INDEX actuel :

Read file_path="best-practices/INDEX.md"

2. Déterminer la catégorie principale parmi ces options (utiliser l'emoji exactement comme indiqué) :

   • 🎯 Conception et orchestration des jobs
   • 🖥️ Gestion et ciblage des nœuds
   • 🔐 Sécurité et contrôle d'accès
   • 📊 Performance et mise à l'échelle
   • 🔗 Intégrations et webhooks
   • 🏗️ Architecture et déploiement
   • 📝 Documentation et maintenance

3. Mettre à jour trois sections avec l'outil Edit :

a) Section Catégories : Trouver la catégorie appropriée (ex. "### 🎯 Conception et orchestration des jobs") et ajouter l'entrée :

- [Titre](./nom-du-fichier.md) - Description en une ligne #tag1 #tag2 #tag3

Insérer par ordre alphabétique dans la catégorie.

b) Tableau Toutes les bonnes pratiques (alphabétique) : Trouver la position alphabétique correcte et insérer :

| [Titre](./nom-du-fichier.md) | Catégorie [et catégories secondaires si applicable] | 2026-04-20 | [Cas connexes ou "N/A"] |

c) Section Référence rapide par cas d'utilisation : Ajouter 2 à 4 entrées "J'ai besoin de..." qui reflètent les cas d'utilisation courants :

- **...problème/tâche spécifique** → [Titre](./nom-du-fichier.md)

Maintenir l'ordre alphabétique.

4. Mettre à jour la date "Dernière mise à jour" : Changer la date en haut :

**Dernière mise à jour :** 2026-04-20

5. Exécuter les mises à jour avec l'outil Edit : Utiliser Edit pour chaque modification (ou les combiner si elles sont proches) :

Edit file_path="best-practices/INDEX.md" old_string="<texte-existant>" new_string="<texte-mis-à-jour>"

Étape 12 : Signaler l'achèvement

Fournir un résumé complet de l'achèvement :

✅ Bonne pratique créée avec succès !

## Détails du document
**Titre :** [Titre complet]
**Fichier :** best-practices/<nom-du-fichier>.md
**Catégorie :** [Catégorie principale]
**Tags :** #tag1 #tag2 #tag3

## Résumé de la recherche
- Base de connaissances : X investigations, Y bonnes pratiques
- Documentation : N pages
- GitHub : P issues
- Jira : Q tickets
- Communauté : [si recherché]
- **Total des sources :** [nombre]

## Sections du document complétées
✓ Cas d'utilisation / Scénario
✓ Recommandation avec [nombre] modèles
✓ Implémentation avec [nombre] exemples de code
✓ Pourquoi cela fonctionne
✓ [nombre] Avantages listés
✓ [nombre] Compromis documentés
✓ [nombre] Alternatives envisagées
✓ Exemples concrets : [liens ou "documentation en attente"]
✓ [nombre] Bonnes pratiques connexes liées
✓ [nombre] Références de documentation officielle

## INDEX.md mis à jour
✓ Ajouté à [Nom de la catégorie]
✓ Ajouté au tableau alphabétique (ligne [N])
✓ Ajout de [nombre] entrées de référence rapide
✓ Date "Dernière mise à jour" mise à jour

## Prochaines étapes
1. Consulter le document à : best-practices/<nom-du-fichier>.md
2. Tester l'implémentation dans un bac à sable si applicable
3. Partager avec l'équipe : `/share-kb "<titre>" best-practices/<nom-du-fichier>.md`
4. Faire le lien depuis les profils clients pertinents si applicable

S'il s'agit d'une mise à jour au lieu d'une création :

✅ Bonne pratique mise à jour avec succès !

## Document mis à jour
**Titre :** [Titre complet]
**Fichier :** best-practices/<nom-du-fichier>.md
[reste du résumé adapté au scénario de mise à jour]

Directives qualité

Qualité de la recherche

• Rechercher au minimum 4 catégories de sources (base de connaissances, documentation, code, outils externes)
• Citer les chemins de fichiers spécifiques pour les références au code/documentation
• Lier les issues GitHub par numéro (#1234)
• Lier les tickets Jira par clé (RUN-1234)
• Vérifier les affirmations communautaires par rapport aux sources officielles
• Signaler les informations non vérifiées ou contradictoires

Qualité du document

• Clarté : Chaque section est immédiatement exploitable ou informative
• Complétude : Toutes les sections du modèle sont remplies (pas de TODOs)
• Basé sur des preuves : Toutes les recommandations sont appuyées par des sources
• Pratique : Inclure des exemples réels de code/configuration, pas seulement du texte
• Honnête : Documenter les compromis et les mises en garde

...

[Section tronquée pour la traduction]