writing-plans

Aperçu

Ce que fait la skill writing-plans

La skill writing-plans vous aide à transformer un product spec ou un document de exigences techniques en un plan complet, prêt pour l’implémentation, avant que quiconque ne touche au code. Elle est pensée pour les situations où vous devez livrer une fonctionnalité ou un changement en plusieurs étapes, et où vous voulez un plan clair et décomposé qu’un autre ingénieur peut suivre sans contexte préalable.

Avec writing-plans, vous générez un plan qui :

• Suppose que la personne qui implémente est un·e développeur·euse compétent·e mais nouveau·elle sur votre codebase et votre domaine.
• Précise clairement quels fichiers créer ou modifier pour chaque partie du travail.
• Met en évidence les tests, mises à jour de documentation et vérifications manuelles nécessaires.
• Décompose le travail en tâches petites, livrables et bien délimitées.

Cela facilite la délégation, la relecture du plan, et limite le scope creep ou les cas limites cachés. La skill reflète des pratiques comme DRY, YAGNI, TDD et les commits fréquents, mais se concentre sur la planification de projet et la décomposition des tâches, pas sur la génération de code.

À qui s’adresse writing-plans ?

Utilisez la skill writing-plans si vous êtes :

• Tech lead ou engineering manager ayant besoin d’une méthode de planification reproductible pour les features et les refactors.
• Développeur ou développeuse individuel·le souhaitant clarifier son approche avant d’implémenter des changements risqués ou transverses.
• Équipe utilisant des subagents ou un travail distribué qui nécessite des plans écrits clairs pour coordonner les contributeurs.

La skill est particulièrement adaptée lorsque :

• Vous disposez d’une spec ou de exigences pour une fonctionnalité, une migration ou une intégration.
• Le travail touche plusieurs fichiers, composants ou services.
• Vous voulez que quelqu’un d’autre puisse implémenter le travail sans vous poser des questions en permanence.

Elle est moins adaptée lorsque :

• Vous êtes encore en phase de brainstorming sur le problème ou la solution (utilisez d’abord une skill d’idéation/brainstorming).
• La tâche est minuscule (p. ex. un correctif sur une seule ligne) et ne justifie pas un plan formel.
• Vous cherchez principalement une code review ou de la génération de code, et non de la planification.

Comment elle s’intègre à votre workflow

Le dépôt suppose que writing-plans est utilisée après une phase de brainstorming et dans un worktree dédié au projet. Le déroulé habituel est :

1. Faire le brainstorming et clarifier la spec (en dehors de cette skill).
2. Créer ou ouvrir un worktree dédié pour la fonctionnalité.
3. Exécuter la skill writing-plans pour produire le plan d’implémentation.
4. Sauvegarder le plan (par défaut) dans :
   • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
   • ou un emplacement de plan préféré que vous définissez.
5. Optionnellement, lancer un plan document reviewer subagent à l’aide du template fourni pour valider le plan avant implémentation.

Utilisation

Installation et configuration

1. Installer la skill writing-plans

Vous pouvez installer la skill directement depuis le dépôt obra/superpowers :

npx skills add https://github.com/obra/superpowers --skill writing-plans

Cela récupère la définition de la skill writing-plans et ses prompts associés pour que vous puissiez l’utiliser dans vos propres projets.

2. Inspecter les fichiers principaux

Après l’installation, consultez ces fichiers clés pour comprendre et adapter le workflow :

• skills/writing-plans/SKILL.md – Description principale du comportement attendu de la skill, incluant le scope, la structure du plan et les hypothèses sur le profil de l’ingénieur.
• skills/writing-plans/plan-document-reviewer-prompt.md – Template de prompt réutilisable pour un subagent qui relit votre plan finalisé.

Vos chemins locaux peuvent varier selon la façon dont vous vendez ou miroitez le dépôt, mais les noms de fichiers restent les mêmes.

Préparer l’exécution de writing-plans

3. Valider votre spec et votre périmètre

Avant d’utiliser writing-plans, assurez‑vous d’avoir :

• Une spec ou un document de exigences clair pour la fonctionnalité ou le changement.
• Assez de détails pour identifier les principaux composants, intégrations et contraintes.

La skill inclut une étape de Scope Check : si votre spec couvre plusieurs sous-systèmes indépendants, elle part du principe que ce travail a été découpé en specs de sous‑projets distincts pendant le brainstorming. Si ce n’est pas le cas, vous devriez :

• Décomposer le travail en plans séparés, un par sous-système.
• Veiller à ce que chaque plan produise un logiciel fonctionnel et testable de manière autonome.

Cela évite qu’un seul plan devienne ingérable et aide à aligner le travail sur des unités déployables.

4. Préparer un worktree et le fichier de plan

Les recommandations upstream supposent que vous :

• Travaillez dans un worktree dédié pour la fonctionnalité (configuré lors du brainstorming).

• Sauvegardez le plan d’implémentation généré sous :

  • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

Vous pouvez surcharger cet emplacement si votre équipe préfère une autre structure de répertoires, comme docs/plans/ ou planning/. L’important est que le plan soit versionné dans le contrôle de version, versionné avec le code et facile à retrouver plus tard.

Lancer la skill et rédiger un plan

5. Annoncer et démarrer la session de planification

Lorsque vous invoquez la skill ou démarrez votre conversation de planification, la recommandation est d’indiquer explicitement :

"I'm using the writing-plans skill to create the implementation plan."

Cela clarifie que l’objectif est un plan d’implémentation structuré, et non une exploration de design ou une sortie de code.

6. Cartographier d’abord la structure de fichiers

Avant de lister les tâches, writing-plans met l’accent sur la décomposition au niveau des fichiers :

• Identifier quels fichiers seront créés ou modifiés.
• Attribuer à chaque fichier une responsabilité unique et claire.
• Concevoir des unités avec des interfaces et frontières bien définies.

À ce stade, le plan doit répondre à :

• Où la nouvelle logique sera‑t‑elle située ?
• Quels fichiers existants sont modifiés, et pourquoi ?
• Comment ces fichiers interagissent‑ils à un niveau macro ?

Verrouiller une structure de fichiers pertinente dès le départ facilite la décomposition en tâches, les reviews et les futurs refactors.

7. Décomposer le travail en tâches “bite-sized”

Une fois la carte des fichiers établie, utilisez writing-plans pour transformer la spec en une séquence de tâches petites et compréhensibles de manière indépendante. Les recommandations upstream insistent sur :

• Chaque tâche doit avoir un objectif clair et être directement actionnable.
• Les tâches doivent être assez petites pour permettre des commits fréquents.
• Le plan doit rester DRY (pas d’instructions redondantes) et éviter le travail YAGNI (pas de tâches spéculatives).

Pour chaque tâche, le plan doit préciser :

• Quels fichiers sont concernés.
• Quels changements de code ou de configuration sont nécessaires, à un niveau macro.
• Quels tests ajouter ou mettre à jour.
• Quelle documentation doit être mise à jour.

L’objectif est qu’un·e ingénieur·e avec un contexte minimal puisse prendre n’importe quelle tâche et la mener à bien en confiance.

8. Prévoir les tests et la documentation

writing-plans vous pousse à intégrer tests et documentation directement dans le plan :

• Identifier les unit tests, tests d’intégration ou end‑to‑end à ajouter ou mettre à jour.
• Indiquer comment lancer les tests (p. ex. commandes, points d’entrée des tests) lorsque c’est pertinent.
• Spécifier les mises à jour de documentation requises, comme des sections de README, guides utilisateur ou docs d’API.

Cela garantit que la qualité et la maintenabilité sont des éléments de premier plan, et pas des ajouts de dernière minute.

Relecture et itérations sur le plan

9. Utiliser le template de plan document reviewer (optionnel mais recommandé)

Le fichier plan-document-reviewer-prompt.md fournit un prompt structuré pour un plan document reviewer subagent. Son rôle est de :

• Vérifier que le plan est complet et conforme à la spec.
• Valider que la décomposition en tâches est réaliste et actionnable.
• Confirmer qu’un·e ingénieur·e peut implémenter le plan sans rester bloqué·e.

Le template énumère les catégories que le reviewer doit contrôler, notamment :

• Completeness – Pas de TODO, de placeholders ou d’étapes manquantes pour les exigences importantes.
• Spec Alignment – Le plan couvre la spec sans scope creep majeur.
• Task Decomposition – Les tâches ont des frontières claires et sont implémentables.
• Buildability – Un·e ingénieur·e compétent·e peut suivre le plan de bout en bout.

Le reviewer est invité à se concentrer sur les points qui causeraient de vrais problèmes d’implémentation, pas sur des détails de style ou de formulation.

Vous pouvez intégrer cette étape de review dans votre CI, vos workflows de revue ou votre processus de relecture manuelle.

10. Itérer à partir des retours

Si le reviewer (humain ou subagent) identifie des problèmes comme des exigences manquantes, des étapes contradictoires ou des tâches trop vagues :

• Mettez à jour le fichier de plan avec les corrections.
• Relancez ou redéclenchez le reviewer si nécessaire.
• Une fois le plan approuvé, considérez‑le comme la source de vérité pour l’implémentation.

Adapter writing-plans à votre équipe

11. Personnaliser la structure et les conventions

Même si la skill upstream définit des comportements et des valeurs par défaut clairs, vous pouvez l’adapter en :

• Modifiant l’emplacement du fichier de plan pour l’aligner sur la structure de votre dépôt.
• Ajoutant des checklists spécifiques à votre équipe (p. ex. revue sécurité, tests de performance) comme tâches récurrentes.
• Intégrant le plan à votre issue tracker en mappant les tâches à des tickets.

Comme writing-plans porte surtout sur un workflow structuré et la gestion de projet, elle se transpose bien à différents langages, frameworks et domaines.

FAQ

Quand dois‑je utiliser la skill writing-plans ?

Utilisez writing-plans dès que vous avez une feature, un refactor ou une intégration en plusieurs étapes avec une spec raisonnablement claire, et que vous voulez un plan d’implémentation écrit qu’un autre ingénieur peut exécuter sans contexte. C’est particulièrement utile avant des changements complexes qui touchent plusieurs fichiers ou sous‑systèmes.

Quand writing-plans n’est‑elle pas adaptée ?

writing-plans n’est pas idéale lorsque :

• Vous explorez encore les solutions et que la spec est instable.
• Le travail est tellement petit qu’un plan formel serait une surcharge.
• Vous cherchez uniquement de la génération de code ou une code review, et non de la décomposition de tâches et de la planification de projet.

Dans ces cas, privilégiez des skills orientées brainstorming, design ou code.

Dois‑je utiliser obligatoirement le chemin par défaut docs/superpowers/plans/ ?

Non. Les recommandations upstream suggèrent d’enregistrer les plans sous :

• docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

Mais elles précisent explicitement que les préférences utilisateur pour l’emplacement des plans priment sur cette valeur par défaut. Vous pouvez conserver vos plans dans n’importe quel répertoire ou schéma de nommage compatible avec les standards de votre dépôt et de votre documentation.

Puis‑je utiliser writing-plans pour des projets non liés au code ?

La skill est conçue pour des projets logiciels et des codebases, avec des mappings de fichiers et des tests. Cependant, les principes de base — découper le travail en petites tâches, clarifier les responsabilités et vérifier l’exhaustivité — peuvent être adaptés à d’autres workflows techniques. Elle sera particulièrement efficace là où il existe au moins une notion de fichiers, de tests ou de documentation à mettre à jour.

Comment writing-plans aide‑t‑elle à l’onboarding et aux handoffs ?

Parce que writing-plans part du principe que la personne qui implémente n’a aucun contexte sur votre codebase et un goût douteux, elle vous incite à :

• Expliquer où le code doit vivre et pourquoi.
• Rendre les tests et la documentation explicites.
• Lever les ambiguïtés dans les tâches.

Cela facilite grandement la transmission du travail à de nouveaux membres d’équipe, des prestataires ou des subagents. Ils peuvent suivre le plan directement au lieu de devoir inférer vos intentions à partir de la spec.

Quel est le lien entre writing-plans et les outils de gestion de projet ?

writing-plans complète les outils de gestion de projet, plutôt que de les remplacer :

• Elle vous fournit un plan écrit structuré expliquant comment implémenter une spec au niveau du code et des fichiers.
• Vous pouvez ensuite mapper les tâches du plan vers des outils comme Jira, GitHub Issues ou Linear.

La skill se situe à l’intersection de la gestion de projet, des templates de workflow et de la rédaction technique, et vous offre un schéma réutilisable pour des plans d’implémentation cohérents.

Puis‑je utiliser uniquement le reviewer prompt sans la skill complète ?

Oui. Le fichier plan-document-reviewer-prompt.md peut être utilisé de façon indépendante comme template de review pour tout document de type plan. Vous pouvez l’utiliser comme prompt de subagent pour :

• Relire des plans écrits avec writing-plans.
• Vérifier des plans créés par d’autres processus ou outils.

Cependant, vous obtiendrez les résultats les plus cohérents lorsque le plan et la review sont tous deux alignés sur le workflow writing-plans.