pedro-oscar/shorts-ai

Demandez à Matt

Vous ne vous souvenez pas de chaque compétence, alors demandez.

Avant de dire ce qu'une compétence fait ou de recommander de sauter une étape, lisez son SKILL.md : les résumés ici ne sont qu'à titre indicatif.

Un flux est un chemin à travers les compétences. La plupart des chemins suivent un flux principal, et deux voies d'accès s'y rejoignent. Tout le reste est autonome, ou une couche de vocabulaire qui s'exécute en dessous.

Le flux principal : idée → mise en production

Le chemin qu'emprunte la plupart du travail. Vous avez une idée et vous voulez la concrétiser.

1. /grill-with-docs affine l'idée par un entretien. Commencez ici chaque fois que vous êtes dans un répertoire de travail : c'est stateful, conservant ce qu'il apprend dans GLOSSARY.md et les ADRs. (Pas de répertoire de travail ? Utilisez /grill-me à la place, couvert sous Autonome. Les deux exécutent la même primitive /grilling ; grill-with-docs est celui qui laisse une trace papier, ce qui en fait le meilleur des deux chaque fois qu'un dépôt est là pour laisser cette trace.)

2. Branchement : pouvez-vous régler chaque question par la conversation ? Si une question nécessite une réponse exécutable (état, logique métier, une interface utilisateur que vous devez voir), faites un détour par un prototype, relié par /handoff dans les deux directions (un prototype vit dans son propre répertoire, ce qui est exactement le but de /handoff ; voir Limites de phase) :

   • /handoff vers l'extérieur, puis ouvrez une nouvelle session sur ce fichier,
   • /prototype pour répondre à la question avec du code jetable,
   • /handoff en retour de ce que vous avez appris, et référencez-le depuis le fil d'idée original.

3. Branchement : s'agit-il d'une construction multi-session ?

   • Oui → /to-spec (transformez le fil en spécification), puis /to-tickets pour le diviser en tickets de balle traceuse, chacun déclarant ses dépendances bloquantes. Ensuite, travaillez les tickets de l'une des deux manières suivantes :
     • /implement par ticket, /clearant le contexte entre chacun. Sur un tracker local, cela signifie un fichier par ticket sous .scratch/<feature>/issues/, travaillé d'abord sur les bloqueurs à la main ; sur un tracker réel, les dépendances deviennent des liens de blocage natifs, donc tout ticket dont les bloqueurs sont terminés peut être pris en charge. Chaque ticket est autonome, donc le contexte du dernier est jetable.
     • /implement-spec pour la spécification entière en une seule exécution. Il lit les tickets comme un graphe de tâches, exécute des sous-agents implémenteurs à travers la frontière prête en parallèle, et rassemble le tout sur une branche d'intégration. Utilisez-le lorsque vous préférez orchestrer la construction plutôt que de piloter chaque ticket vous-même.
   • Non → /implement ici même, dans la même fenêtre de contexte.

   Dans les deux cas, le code est construit en pilotant /tdd (une tranche rouge-vert à la fois) et se termine par /code-review, une revue à deux axes (Normes + Spécification) du diff. /implement exécute les deux par ticket ; les implémenteurs de /implement-spec pilotent chacun /tdd, et il exécute une /code-review sur la branche d'intégration. Utilisez /tdd seul lorsque vous voulez simplement construire un comportement concret en mode test-first sans spécification complète, et /code-review seul chaque fois que vous voulez examiner une branche ou une PR par rapport à un point fixe.

   Lorsque le travail est soumis en tant que pull request, /pr façonne le corps : le plus petit visuel qui montre le changement, les preuves avant/après que cela fonctionne, et un appel sur la nature de la décision (réversible ou irréversible). Il est invoqué par le modèle, donc l'agent l'utilise chaque fois qu'il rédige une PR.

4. /retro boucle la boucle. Après une construction, et surtout une qui a mal tourné, il examine la session et suggère des changements à l'environnement de l'agent, pas au code : des pointeurs de navigation, des vérifications automatisées, les normes de codage que /code-review applique, des fichiers de pilotage, des outils. Les erreurs mécaniques deviennent des vérifications déterministes ; les jugements deviennent des normes de codage. La construction suivante part alors d'un meilleur environnement.

Hygiène du contexte

Gardez les étapes 1 à 3 dans une seule fenêtre de contexte ininterrompue (ne compactez ni n'effacez avant /to-tickets) pour que le grillage, la spécification et les tickets reposent tous sur la même réflexion. Chaque /implement commence alors frais, à partir du ticket. Exécutez /retro dans la session qu'il examine, avant d'effacer ; après avoir effacé, pointez-le vers le journal de cette session à la place.

La limite à cela est la zone intelligente : la fenêtre (~150k tokens sur les modèles de pointe) dans laquelle le modèle raisonne encore avec précision. Si une session s'en approche avant /to-tickets, ne continuez pas sur un modèle dégradé ; /compact à la limite de phase la plus proche et continuez (voir Limites de phase).

Voies d'accès

Une situation de départ qui génère du travail, puis rejoint le flux principal.

• Les bugs et les demandes s'accumulent → /triage. Il déplace les problèmes à travers les rôles de triage et produit des problèmes prêts pour l'agent, que /implement récupère plus tard.

  Le triage est uniquement pour les problèmes que vous n'avez pas créés : rapports de bugs, demandes de fonctionnalités entrantes, tout ce qui arrive brut. Les tickets que /to-tickets a produits sont déjà prêts pour l'agent, donc ne les triez pas.

• Quelque chose est cassé → /diagnosing-bugs. Pour les cas difficiles : le bug qui résiste à un premier coup d'œil, le problème intermittent, la régression qui s'est glissée entre deux états connus comme bons. Il refuse de théoriser avant d'avoir une boucle de rétroaction serrée (une commande qui devient déjà rouge sur ce bug), puis corrige avec un test de régression. Une fois le correctif en place, exécutez /retro dans la même session pour demander ce qui aurait évité le bug ; lorsque la véritable découverte est qu'il n'y a pas de bonne couture pour le verrouiller, c'est un travail pour /improve-codebase-architecture.

• Un effort énorme et flou : un projet greenfield ou une construction de fonctionnalité massive, trop grande pour une seule session → /wayfinder, le flux le plus exigeant cognitivement ici. Lorsque le chemin d'ici à la destination n'est pas encore visible, il trace une carte partagée de tickets de décision sur le tracker de problèmes et les résout un par un, produisant des décisions, pas des livrables, jusqu'à ce que le brouillard soit repoussé et que la voie soit claire. Là où /grill-with-docs affine une idée que vous pouvez contenir en une session, wayfinder est pour l'idée que vous ne pouvez pas, et il est plus lent et plus dense, donc réservez-le exactement pour cela, jamais pour une fonctionnalité bien délimitée.

  Lorsque la carte se clarifie, elle passe le relais, elle ne construit pas : rejoignez le flux principal à /to-spec, qui condense les décisions liées de la carte en un plan constructible, puis /to-tickets et /implement comme d'habitude. Boucler la carte directement dans /implement saute cette condensation et jette les détails liés, donc allez directement à /implement uniquement lorsque l'effort s'avère véritablement petit.

Santé de la base de code

Pas du travail sur les fonctionnalités, juste de l'entretien.

• /improve-codebase-architecture s'exécute chaque fois que vous avez un moment libre pour garder la base de code en bon état pour que les agents y opèrent. Il fait remonter les opportunités d'approfondissement ; en choisir une génère une idée que vous pouvez emmener dans le flux principal à /grill-with-docs. C'est l'enquête qui trouve les candidats ; /codebase-design (ci-dessous) est l'établi sur lequel vous concevez celui que vous avez choisi.

Vocabulaire sous-jacent

Deux références invoquées par le modèle qui s'exécutent sous les autres compétences, chacune étant la source unique de vérité pour son vocabulaire. Utilisez-les directement lorsque les mots, et non le processus, sont le problème ; ou laissez les compétences ci-dessus les invoquer.

• /domain-modeling : affine le langage domaine du projet : contester un terme flou, résoudre un mot surchargé (« compte » faisant trois emplois), enregistrer une décision difficile à inverser en tant qu'ADR. C'est la discipline active que /grill-with-docs pilote pour maintenir GLOSSARY.md comme un glossaire propre.
• /codebase-design est le vocabulaire des modules profonds (module, interface, profondeur, couture, adaptateur, levier, localité) pour concevoir la forme d'un module : beaucoup de comportement derrière une petite interface à une couture propre. /tdd et /improve-codebase-architecture parlent tous les deux ce langage.

Limites de phase

Une phase est un morceau de travail à l'intérieur d'une session : le grillage, l'implémentation, l'assurance qualité. À la limite entre deux d'entre elles, vous avez cinq options, et choisir entre elles est la décision la plus floue de toute cette carte :

• Continuer : rester où vous êtes. Ne coûte rien, ne perd rien.
• /clear : vider la fenêtre, quand rien ici n'a d'importance pour la suite.
• /handoff écrit un fichier markdown portable. Étroit : uniquement pour un nouveau harnais, un nouveau répertoire, un collègue, ou pour bifurquer une tâche secondaire en milieu de phase. Ce qu'il apporte, c'est la portabilité.
• Sous-agent : envoyer une tâche étroitement délimitée dans sa propre fenêtre et obtenir un rapport en retour.
• /compact compresse ce contexte et amorce une nouvelle session avec. Le par défaut, au bas de l'arbre plutôt que la première branche atteinte.

Lisez PHASE-BOUNDARIES.md pour l'arbre ordonné : les cinq questions, le raisonnement derrière chaque branche, et pourquoi le coût de la source principale fait de Continuer celui à exclure en premier. Prenez la décision à une limite ; en milieu de phase, continuez ou divisez le reste en sous-agents.

Autonome

Hors du flux principal.

• /grill-me : le même entretien implacable que /grill-with-docs, mais sans état : il ne sauvegarde rien localement et ne construit pas de GLOSSARY.md. Utilisez-le lorsque vous ne travaillez pas dans un répertoire de travail (affiner un plan, une conception, un écrit, tout ce qui n'a pas de dépôt en dessous). Si vous êtes dans un répertoire de travail, utilisez plutôt /grill-with-docs : il exécute le même entretien et laisse une trace papier, donc il est strictement meilleur.
• /grilling est la primitive d'entretien elle-même : tours, frontière, les faits sont le travail de l'agent et les décisions sont les vôtres. /grill-me et /grill-with-docs sont les deux voies nommées, et /triage, /wayfinder et /improve-codebase-architecture l'exécutent tous en interne. Utilisez-le directement uniquement lorsque vous voulez l'entretien sans aucune enveloppe autour.
• /prototype est un petit programme jetable qui répond à une question de conception : ce modèle d'état semble-t-il correct, ou à quoi devrait ressembler cette interface utilisateur. Jetable est une contrainte sur la façon dont le code est écrit, pas une promesse de le détruire : la réponse est intégrée dans le code réel, et le prototype lui-même est conservé comme source primaire sur une branche prototype/<nom> issue de main, pointée depuis le problème d'implémentation. C'est le détour à l'étape 2 du flux principal, mais utilisez-le à tout moment où une question de conception est difficile à trancher sur le papier.
• /research : déléguer le travail de lecture à un agent d'arrière-plan : il étudie une question à partir de sources primaires, puis laisse un fichier Markdown cité dans le dépôt. Continuez à travailler pendant qu'il lit. Le fichier qu'il produit est quelque chose à emmener dans le flux principal à /grill-with-docs, car la recherche alimente la réflexion plutôt que de la remplacer.
• /to-questionnaire intervient lorsque ce qui vous bloque n'est ni dans votre tête ni dans la base de code, mais dans celle de quelqu'un d'autre, et il leur rédige un questionnaire à remplir. C'est l'inverse de /grill-me : au lieu de vous interviewer sur le sujet, il vous interviewe sur l'envoi (à qui cela va, ce dont vous avez besoin en retour) et oriente les questions sur le fossé. Ce qui revient est du matériel pour /grill-with-docs ou /to-spec.
• /wizard est pour les étapes que seul un humain peut effectuer : provisionnement d'infrastructure, configuration d'identifiants ou de secrets CI, navigation dans un tableau de bord tiers inconnu, exécution d'une migration ou d'un basculement ponctuel. Il génère un script bash interactif qui ouvre chaque URL, capture chaque valeur et l'écrit dans .env et les secrets GitHub, de sorte que la procédure cesse d'être quelque chose que vous réexpliquez à un agent à chaque fois. Invoqué par le modèle, donc l'agent l'utilise dès qu'il rencontre un mur que vous seul pouvez franchir. Si l'agent pouvait le faire lui-même, il devrait le faire ; c'est pour quand un humain est véritablement dans la boucle.
• /wait-what est le correctif pour un message qui n'a pas atterri. Utilisez-le en cours de conversation, à l'intérieur de n'importe quelle autre compétence, et l'agent reformule ce qu'il vient de dire avec le contexte qui vous manquait, en anglais simple, en utilisant le vocabulaire de GLOSSARY.md. Il fonctionne après coup ; /grill-with-docs est le remède préventif, car un langage partagé convenu tôt est ce qui empêche le jargon d'arriver du tout.
• /teach : apprenez un concept sur plusieurs sessions, en utilisant le répertoire courant comme espace de travail avec état.
• /writing-for-agents est la référence pour rédiger des documents que les agents consomment : compétences, AGENTS.md, documents pointés.

Précondition

/setup-matt-pocock-skills : exécutez avant votre premier flux d'ingénierie pour configurer le tracker de problèmes, les étiquettes de triage et la disposition des documents que les autres compétences supposent. Les trackers de problèmes personnalisés fonctionnent également.