grill-with-docs

Vue d’ensemble de la skill grill-with-docs

grill-with-docs est une skill de planification et de documentation pour les équipes qui veulent mettre à l’épreuve une conception à partir du langage et des décisions déjà présents dans leur dépôt. Elle est particulièrement adaptée à la rédaction technique, au travail d’ingénierie orienté produit et aux travaux d’architecture assistés par IA, lorsque les termes doivent rester alignés sur CONTEXT.md et les ADR au lieu de dériver vers un langage vague de type « prompt only ».

Sa mission principale est simple : interroger l’utilisateur une question à la fois, proposer des réponses, et s’appuyer sur le codebase ou la documentation lorsqu’une question peut être résolue à partir des sources. Cela rend la skill grill-with-docs plus utile qu’un simple prompt de brainstorming quand le vrai risque est un décalage de terminologie, des hypothèses non documentées ou des enregistrements de décisions obsolètes.

Ce qui distingue grill-with-docs

Cette skill repose sur la connaissance du domaine, pas seulement sur la conversation. Elle vous incite à vérifier les fichiers de contexte existants, à parcourir les ADR et à mettre à jour la documentation à mesure que les décisions se précisent, ce qui explique pourquoi elle fonctionne bien pour grill-with-docs for Technical Writing et d’autres workflows fortement documentaires.

Cas d’usage les plus adaptés

Utilisez grill-with-docs lorsque vous devez :

• valider un plan par rapport à un modèle de domaine existant,
• choisir une terminologie de projet précise,
• consigner les décisions au fil de l’eau,
• ou garder un brouillon aligné sur la documentation établie avant le début de l’implémentation.

Quand ce n’est pas le bon choix

Si vous voulez seulement un résumé rapide, un cahier des charges poli ou une séance d’idéation libre sans ancrage dans le dépôt, cette skill paraîtra plus lente qu’un prompt classique. Sa valeur vient d’un questionnement discipliné et d’une vérification attentive à la documentation.

Comment utiliser la skill grill-with-docs

Installer grill-with-docs

Installez la skill grill-with-docs dans votre répertoire de skills avec le gestionnaire standard du dépôt, puis ouvrez les fichiers de la skill dans le contexte du projet cible. Le schéma d’installation de base est le suivant :

npx skills add mattpocock/skills --skill grill-with-docs

Considérez cela comme le point de départ de grill-with-docs install, puis vérifiez que la skill est bien disponible dans l’environnement d’agent que vous utilisez réellement.

Commencer avec la bonne entrée

La skill fonctionne mieux si votre premier message contient :

• l’objectif que vous planifiez,
• le nom du système ou de la fonctionnalité,
• les termes déjà connus qui comptent,
• et la frontière de décision que vous voulez clarifier.

Un mauvais prompt dit : « Aide-moi à concevoir cette fonctionnalité. »
Un prompt plus solide dit : « Utilise grill-with-docs pour passer ce plan de fonctionnalité au crible du domaine billing actuel. J’ai besoin du bon terme pour “subscription period”, de la structure des données et de toutes les décisions qui méritent un ADR avant d’écrire la documentation. »

Lire ces fichiers en premier

Pour grill-with-docs usage, commencez par :

• SKILL.md pour le comportement d’interview et le workflow,
• CONTEXT.md ou CONTEXT-MAP.md pour le modèle de domaine actif,
• docs/adr/ pour les décisions antérieures,
• ADR-FORMAT.md et CONTEXT-FORMAT.md si vous devez créer ou mettre à jour des fichiers.

Ces fichiers indiquent ce qui peut être déduit du dépôt et ce qui doit être écrit explicitement.

Le workflow qui améliore les résultats

Utilisez la skill en boucle :

1. donnez un plan concret ou un brouillon approximatif,
2. laissez la skill poser une question à la fois,
3. répondez avec le niveau de détail le plus précis possible, en vous appuyant sur le dépôt,
4. autorisez l’exploration du codebase lorsque la question peut être résolue à partir des fichiers,
5. consignez la terminologie et les décisions importantes dans le contexte ou dans des notes d’ADR.

L’astuce pratique essentielle : séparez « il nous faut un nom » de « il nous faut une décision ». Cela permet de garder le grill concentré et d’éviter des ADR inutiles.

FAQ sur la skill grill-with-docs

grill-with-docs est-elle réservée aux équipes de documentation ?

Non. Elle est utile dès qu’un plan doit correspondre à un vocabulaire de domaine existant, en particulier dans l’ingénierie produit, le travail plateforme ou les workflows grill-with-docs for Technical Writing, où le wording et la structure influencent la clarté en aval.

En quoi est-ce différent d’un prompt normal ?

Un prompt classique peut générer des idées, mais grill-with-docs est conçu pour interroger les hypothèses, vérifier le dépôt et resserrer la terminologie par rapport au contexte existant. Cela réduit le risque de collisions de noms et de documentation qui entre en conflit avec le codebase.

Faut-il une base documentaire très mûre pour l’utiliser ?

Non, mais la skill fonctionne mieux quand CONTEXT.md et des ADR existent déjà. Si ce n’est pas le cas, elle peut quand même vous aider à les définir progressivement au fil des décisions.

Quand faut-il éviter de l’utiliser ?

Évitez-la lorsque la tâche est purement exploratoire, que le dépôt n’a pas de véritable contexte métier, ou que vous avez besoin d’une réponse rapide en une seule passe plutôt que d’un entretien structuré.

Comment améliorer la skill grill-with-docs

Lui donner de meilleurs matériaux de décision

Le plus gros gain de qualité vient d’un prompt étroit et construit autour d’une décision. Incluez le nom de la fonctionnalité, la partie du système qu’elle touche et l’ambiguïté exacte à résoudre. Exemple : « Faut-il appeler cela invoice, billing record ou charge dans le contexte comptable, et où cette décision doit-elle être consignée ? »

Lui donner tôt des preuves du dépôt

Si vous connaissez déjà les fichiers pertinents, mentionnez-les dès le départ. Pointer la skill vers CONTEXT.md, un ADR précis ou un dossier comme src/billing/ l’aide à poser moins de questions génériques et davantage de questions utiles. C’est particulièrement important pour grill-with-docs usage, car la skill est la plus forte lorsqu’elle peut comparer votre plan aux termes et à la structure existants.

Surveiller les modes d’échec fréquents

Le principal échec consiste à sous-spécifier le domaine, ce qui laisse l’entretien trop abstrait. Un autre consiste à demander l’implémentation avant que le modèle n’ait les bons termes. Si la première sortie vous paraît trop large, reformulez la décision en termes plus précis et demandez à la skill de continuer à partir de la dernière branche résolue.

Itérer dès le premier passage

Après le premier tour, transformez les réponses en l’un de ces trois livrables : une entrée de glossaire nettoyée, un ADR court, ou un brief d’implémentation révisé. Puis relancez grill-with-docs sur les questions encore ouvertes. C’est souvent lors de ce deuxième passage que la skill apporte le plus de valeur, parce que la terminologie et les frontières sont déjà plus claires.