yasukei/agent-skills - Création d'issues GitHub

Création d'issues GitHub

Compétence pour rédiger une issue selon un format défini par l'utilisateur. L'objectif est de produire une issue « avec une structure cohérente à chaque fois, permettant de commencer et de valider le travail en la lisant ». En particulier, les critères d'acceptation (Acceptance criteria) sont utilisés ultérieurement comme conditions de complétion lors de l'implémentation (issue-to-pr) ou de la révision. Ils doivent donc être rédigés de manière vérifiable.

1. Vérifier d'abord les templates du dépôt

Si le dépôt possède des templates, ils prévalent sur ceux de cette compétence. Les emplacements à vérifier :

• .github/ISSUE_TEMPLATE/ : fichiers *.md et *.yml / *.yaml (config.yml est un fichier de configuration, pas un template).
• .github/ISSUE_TEMPLATE.md, ISSUE_TEMPLATE.md à la racine, docs/ISSUE_TEMPLATE.md.
• Si rien n'est trouvé, vérifier le dépôt commun de l'organisation : <owner>/.github aux mêmes emplacements.

Si un clone local existe, lire les fichiers directement. Sinon, les récupérer via gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE.

Une fois un template trouvé :

• Choisir celui qui correspond au type d'issue (tâche / bug) en fonction du nom du fichier, du champ name, about ou labels.
• Respecter la structure d'en-têtes du template ; ne pas mélanger avec les en-têtes de cette compétence. Ajouter uniquement à la fin les informations importantes qui n'ont pas de place désignée (comme les dépendances), en une courte phrase.
• Dans le cas d'un formulaire YAML (issue form), GitHub stocke le contenu soumis en utilisant attributes.label de chaque champ comme en-tête ### <label>. Construire le corps de la même manière, et remplir obligatoirement les champs marqués required: true.
• Appliquer le title (préfixe), les labels et les assignees définis dans le frontmatter ou la définition du formulaire.

Si aucun template ne correspond au type d'issue (ex. template bug présent mais pas de template tâche), utiliser uniquement le template ci-dessous pour ce type.

2. Déterminer le type

• Tâche : nouvelle fonctionnalité, amélioration, refactoring, documentation, CI, investigation, etc. → Template Tâche.
• Bug : correction de quelque chose qui ne fonctionne pas comme prévu. → Template Bug.

En cas de doute, se demander : « Le comportement actuel est-il contraire à la spécification ? » Si oui, c'est un bug.

3. Template Tâche

## Goal

<En 1 à 2 phrases, ce qui doit être accompli. Ajouter brièvement pourquoi c'est nécessaire.>

## Scope

- <Ce qui est fait. Si plusieurs groupes, les organiser avec des **sous-titres en gras**>

## Out of scope

- <Ce qui n'est pas fait. Mentionner les domaines adjacents qui pourraient être mal interprétés>

## Acceptance criteria

- <Conditions vérifiables pour valider la complétion : tests, CI, résultats de commandes, etc.>

## Depends on

- #<numéro>

Part of #<numéro de l'issue parent>.

Points de rédaction :

• Goal : inclure non seulement « quoi » mais aussi « pourquoi ». Cela permet à quelqu'un qui lit plus tard de comprendre la priorité et la justification.
• Scope : être suffisamment granulaire pour que l'implémenteur ne soit pas perdu. Mentionner les noms de types, commandes, fichiers, etc. Si des éléments sont reportés d'une revue précédente, les séparer avec un sous-titre explicite.
• Out of scope : écrire explicitement ce qui n'est pas fait pour éviter le scope creep. S'il n'y a rien, écrire - None et conserver la section (pour montrer qu'elle n'a pas été oubliée).
• Acceptance criteria : préférer des formulations vérifiables par un tiers, comme « le test X existe et passe » ou « CI exécute Y avec succès », plutôt que « X est implémenté ».
• Depends on : lister les issues qui doivent être terminées avant, sous la forme - #numéro (GitHub affichera le titre). S'il n'y en a pas, écrire - None.
• Si l'issue est une sous-tâche issue d'une issue parent, ajouter Part of #<numéro>. à la fin.
• N'ajouter une section ## Notes après Acceptance criteria que s'il y a des documents de référence, des liens ou des décisions en attente. Ne pas en créer artificiellement.

4. Template Bug

## Summary

<En 1 à 2 phrases, ce qui se passe>

## Steps to reproduce

1. <étape>
2. <étape>

## Expected behavior

<Ce qui devrait se passer>

## Actual behavior

<Ce qui se passe réellement. Coller les messages d'erreur ou les logs dans des blocs de code>

## Environment

- Version / commit : <version ou hash de commit>
- <OS / navigateur / Node / etc. selon le contexte>

## Acceptance criteria

- Les étapes ci-dessus doivent produire le comportement attendu.
- Un test de régression reproduisant ce bug est ajouté et passe.

## Notes

<Pistes de cause, issues/PR liées, contournements. Supprimer cette section si rien à noter>

Points de rédaction :

• N'écrire que les étapes, l'environnement et les logs que vous avez recueillis de l'utilisateur ou vérifiés vous-même. Si une information est inconnue, écrire Unknown ou demander à l'utilisateur. Ne pas inventer de procédure de reproduction, cela fausserait l'investigation.
• Séparer clairement les causes présumées (dans Notes) des faits observés (Actual behavior). Mélanger symptômes et hypothèses rend l'issue difficile à lire si l'hypothèse est fausse.
• Si la direction de correction est déjà décidée, l'écrire dans Notes.

5. Titre, labels et métadonnées

• Le titre suit le format <area>: <contenu> (ex. core: data types, tree IR, and UI–runtime protocol). L'area correspond aux labels existants area:* du dépôt. Pour un bug, décrire le symptôme, pas la correction (ex. runtime: TON timer does not fire after coldReset).
• Les labels sont choisis parmi ceux existants (gh label list). Ajouter bug s'il existe pour les bugs. Ne pas créer de labels inexistants.
• Si le milestone ou l'issue parent est connu, le définir.
• La langue du titre et du corps correspond à celle des issues et PR existants du dépôt (vérifier avec gh issue list --state all --limit 10 et gh pr list --state all --limit 10). S'il n'y a ni issue ni PR existant, rédiger en français.
• Les noms de sections (Goal, Scope, Summary, Steps to reproduce, etc.) restent en anglais même si le corps est en français. Cependant, si vous utilisez un template du dépôt, utiliser exactement ses en-têtes.

6. Créer l'issue

Écrire le corps dans un fichier temporaire, puis le passer via --body-file (pour éviter les problèmes de quoting shell).

gh issue create --repo <owner>/<repo> \
  --title "<title>" --body-file /tmp/issue-body.md \
  --label "<label>" --milestone "<milestone>"

• Si l'utilisateur a explicitement demandé de créer l'issue, la créer directement. Si l'utilisateur demande seulement un brouillon, ou si une grande partie du contenu est spéculative, montrer le corps pour confirmation avant de créer.
• S'il y a une issue parent, en plus de la mention Part of #N. dans le corps, lier l'issue en tant que sous-issue via l'API GitHub (POST /repos/<owner>/<repo>/issues/<parentId>/sub_issues avec l'id de l'enfant). Si l'API ne fonctionne pas, la mention textuelle suffit.
• Si vous créez plusieurs issues en une fois, les créer dans l'ordre de dépendance (celles qui sont dépendantes d'abord), afin que les numéros dans Depends on soient corrects.
• Après création, communiquer l'URL de l'issue à l'utilisateur.