writing-plans

Vue d’ensemble de la skill writing-plans

Ce que fait la skill writing-plans

La skill writing-plans vous aide à transformer une spec de fonctionnalité ou un document d’exigences en plan d’implémentation détaillé avant de commencer à coder. Son rôle principal n’est pas de générer des idées, mais de produire un plan exécutable et révisable, en partant du principe que la personne qui implémente connaît peu la base de code et a malgré tout besoin d’indications claires au niveau des fichiers, des étapes de test et de l’ordre d’exécution des tâches.

À qui s’adresse writing-plans

Cette skill est particulièrement adaptée aux ingénieurs, aux tech leads et aux workflows pilotés par agent qui disposent déjà d’un besoin bien cadré et ont maintenant besoin d’un plan d’exécution pour le Requirements Planning. Elle est particulièrement utile lorsque le travail s’étend sur plusieurs fichiers, touche aux tests et à la documentation, ou sera transmis à quelqu’un d’autre que l’auteur initial de la spec.

Le vrai besoin auquel elle répond

Les utilisateurs de writing-plans cherchent généralement à réduire la part d’incertitude au moment d’implémenter. La valeur n’est pas seulement de “faire un plan”, mais de “faire un plan qu’un ingénieur compétent peut suivre sans hypothèses cachées”. Cela inclut les fichiers à modifier, la manière de découper le travail en tâches de petite taille, ce qu’il faut tester et les points où il vaut mieux scinder le périmètre avant de commencer l’implémentation.

Ce qui distingue cette skill d’un prompt générique

La writing-plans skill prend des positions utiles et concrètes :

• elle impose une vérification du périmètre avant le découpage
• elle demande de cartographier le rôle des fichiers avant de rédiger les tâches
• elle privilégie de petits incréments testables plutôt que de grandes phases
• elle part du principe que la personne qui implémente dispose d’un contexte métier limité
• elle inclut un prompt de relecture pour vérifier que le plan est réellement implémentable

Elle est donc plus solide qu’un simple prompt du type “write me an implementation plan” dès lors que la qualité de transmission compte.

Quand writing-plans est un très bon choix

Utilisez writing-plans si vous avez :

• une spec, un ticket ou un document d’exigences déjà rédigé
• une évolution en plusieurs étapes avec un vrai niveau de détail d’implémentation
• un besoin de coordonner code, tests et documentation
• un dépôt où les frontières entre fichiers et l’ordre des étapes ont de l’importance

Si vous avez seulement besoin d’un plan rapide ou d’une estimation grossière, cette skill peut être plus lourde que nécessaire.

Comment utiliser la skill writing-plans

Contexte d’installation de writing-plans

Le dépôt n’expose pas d’installateur dédié au niveau du package à l’intérieur de la skill elle-même. En pratique, la voie d’writing-plans install consiste donc à ajouter la collection parente, puis à invoquer cette skill depuis celle-ci :

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

Si votre environnement utilise un autre chargeur de skills, installez la collection obra/superpowers et sélectionnez writing-plans depuis skills/writing-plans.

Commencez par lire ces fichiers

Pour une évaluation rapide, commencez par :

• skills/writing-plans/SKILL.md
• skills/writing-plans/plan-document-reviewer-prompt.md

SKILL.md décrit le workflow réel de planification. Le prompt de relecture montre le niveau d’exigence attendu pour le plan, ce qui est utile avant de décider d’utiliser la skill en production.

Les entrées dont la skill a besoin

L’writing-plans usage est meilleur si vous fournissez :

• la spec source ou les exigences
• le dépôt cible ou la zone de la base de code concernée
• les contraintes d’architecture, d’outillage, de délais ou de rétrocompatibilité
• l’emplacement souhaité pour le plan si vous ne voulez pas utiliser celui par défaut
• l’indication de savoir si le travail doit être découpé en plusieurs plans indépendants

Sans vraie spec, la skill tend à produire une structure plausible, mais des indications d’implémentation moins solides.

Commencez par l’annonce requise

Les instructions amont demandent explicitement à l’agent d’annoncer :

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

Si vous intégrez cette skill dans un workflow agentique, conservez cette ligne. Elle rend l’invocation visible et réduit l’ambiguïté sur le standard de planification appliqué.

Utilisez-la avant le code, idéalement dans un worktree dédié

La skill est pensée pour la planification pré-implémentation et suppose qu’elle s’exécute dans un worktree dédié, créé en amont par un workflow de brainstorming. Même si vous n’utilisez pas exactement cette configuration compagnon, l’intention reste importante : planifier dans un contexte isolé avant de modifier le code, afin que le plan soit un artefact volontaire et non un simple sous-produit du codage.

Transformer un objectif flou en prompt solide

Prompt faible :

• “Make a plan for adding billing.”

Prompt plus solide :

• “Use the writing-plans skill to create an implementation plan for adding team billing to our SaaS app. Spec: docs/specs/team-billing.md. Repo areas likely involved: apps/web, services/billing, db/schema. Constraints: Stripe is already used for individual billing, do not break existing subscriptions, include migration and rollback considerations, and call out tests and docs. If the spec spans independent subsystems, propose separate plans.”

Pourquoi cela fonctionne :

• la spec est nommée explicitement
• les fichiers ou modules probables sont indiqués
• les contraintes qui influencent le découpage sont précisées
• cela permet de proposer une séparation du périmètre au lieu de forcer un plan unique trop volumineux

Respectez la séquence de planification de la skill

Un bon writing-plans guide doit suivre l’ordre implicite du dépôt :

1. vérifier si la spec doit être découpée en plusieurs plans
2. cartographier les fichiers et leurs responsabilités avant de détailler les tâches
3. rédiger des tâches d’implémentation de petite taille
4. inclure les tests, la documentation et les étapes de validation
5. relire le plan final par rapport à la spec

Sauter l’étape de structure des fichiers est la manière la plus courante d’obtenir des tâches vagues.

Ce qu’un bon résultat doit contenir

Un bon plan produit par writing-plans for Requirements Planning doit en général inclure :

• l’objectif du plan et la spec associée
• les fichiers à créer ou à modifier
• pourquoi chaque fichier existe ou doit être modifié
• des tâches assez petites pour être réalisées et vérifiées indépendamment
• des indications de test, pas seulement des étapes de développement
• les mises à jour de documentation ou de migration si elles sont pertinentes
• assez de détails pour qu’un autre ingénieur ne se retrouve pas bloqué

Si le résultat se limite surtout à de grandes phases thématiques comme “backend”, “frontend” ou “QA”, il est probablement trop grossier.

Emplacement par défaut du plan et quand le remplacer

La skill recommande d’enregistrer les plans dans :

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

Remplacez cet emplacement si votre dépôt suit déjà une convention de planification, par exemple docs/plans/ ou specs/implementation/. L’essentiel est de garder de la cohérence et un chemin que les reviewers pourront retrouver plus tard.

Comment utiliser le prompt de relecture

Après avoir rédigé le plan, utilisez plan-document-reviewer-prompt.md comme modèle de relecture en seconde passe. Ses critères sont concrets :

• exhaustivité
• alignement avec la spec
• qualité du découpage des tâches
• caractère implémentable

C’est un vrai point différenciant de la writing-plans skill : elle ne s’arrête pas à la génération, elle fournit aussi une vérification légère mais utile pour valider le plan produit.

Un workflow pratique qui fonctionne bien

Un workflow fiable ressemble à ceci :

1. rassembler la spec et le contexte du dépôt
2. exécuter writing-plans
3. vérifier si le découpage du plan est correct
4. relire les frontières entre fichiers et la granularité des tâches
5. exécuter le prompt de relecture du plan
6. réviser le plan avant le début de l’implémentation

C’est dans ce rôle de garde-fou de planification, et pas seulement comme aide à la rédaction, que la skill apporte le plus de valeur.

FAQ sur la skill writing-plans

writing-plans est-elle adaptée aux débutants ?

Oui, si le débutant dispose déjà d’une spec raisonnablement concrète. La skill compense le manque de contexte sur la base de code en imposant des indications explicites sur les fichiers et les tests. Elle est moins utile lorsque le vrai problème tient encore à une réflexion produit trop floue.

Quelle différence avec le fait de demander simplement à une IA un plan d’implémentation ?

Les prompts génériques produisent souvent des plans bien présentés, mais superficiels. writing-plans est plus utile parce qu’elle pousse au découpage au niveau des fichiers, à la testabilité et à une meilleure qualité de transmission vers la personne qui implémente. En pratique, cela réduit souvent les retouches une fois le développement commencé.

Quand ne faut-il pas utiliser writing-plans ?

Mieux vaut l’éviter si :

• le changement est minime et localisé
• vous êtes encore en train de définir le périmètre produit
• vous avez davantage besoin d’exploration architecturale que de planification d’exécution
• le travail est volontairement expérimental et risque de changer immédiatement

Dans ces cas-là, des notes légères peuvent être plus adaptées qu’un plan formel.

Exige-t-elle une stack ou un framework particulier ?

Non. La skill est orientée processus, pas framework. Ses conseils sont transposables d’une stack à l’autre parce qu’ils portent avant tout sur le découpage, les responsabilités des fichiers, les tests et la capacité de relecture.

writing-plans peut-elle gérer de grosses specs ?

Oui, mais seulement si vous respectez l’étape de vérification du périmètre. La source avertit explicitement que plusieurs sous-systèmes indépendants doivent en général devenir des plans distincts. Si vous forcez un plan géant, la qualité des tâches baisse généralement.

writing-plans suffit-elle à elle seule pour le Requirements Planning ?

Pour un Requirements Planning orienté implémentation, souvent oui. Pour des exigences encore en phase de découverte, non. Elle part du principe que vous savez déjà ce qu’il faut construire et que vous avez maintenant besoin d’un chemin fiable pour le faire.

Comment améliorer la skill writing-plans

Donnez un contexte dépôt plus précis

La manière la plus simple d’améliorer les résultats de writing-plans consiste à nommer les répertoires, modules ou fichiers probables. La skill cherche à cartographier tôt les responsabilités des fichiers ; si vous indiquez les points de contact les plus plausibles, le résultat devient plus concret et moins générique.

Séparez dès le départ les sous-systèmes indépendants

Si votre spec mélange des sujets sans lien direct, séparez-les avant de demander un plan final. Exemple :

• changements d’authentification
• changements de facturation
• changements d’UI d’administration

Ces sujets peuvent sortir ensemble du point de vue produit, tout en méritant des plans distincts s’ils peuvent être implémentés et testés indépendamment.

Demandez explicitement la cartographie des responsabilités par fichier

Si le premier jet reste vague, demandez :

• “List each file to add or modify and state its responsibility before writing tasks.”

Cela colle très étroitement à la structure de la skill et corrige généralement un découpage trop flou.

Imposer une granularité de tâche plus fine

Un échec fréquent consiste à avoir des tâches trop grosses pour être implémentées sereinement. Demandez :

• des tâches qui produisent une progression testable
• des frontières claires pour chaque tâche
• une validation explicite après chaque changement majeur

C’est sur ce point que l’writing-plans usage progresse le plus : des tâches plus petites sont plus faciles à relire, à assigner et à exécuter.

Rendez les exigences de test concrètes

Ne demandez pas seulement “include tests”. Précisez plutôt :

• quels niveaux de test comptent
• quelles suites de tests existantes doivent être mises à jour
• si des vérifications de migration, d’intégration ou de régression sont requises

La skill accorde déjà de l’importance aux tests, mais de meilleures contraintes rendent le plan beaucoup plus exploitable.

Améliorez le premier jet par itérations guidées par la relecture

Utilisez le modèle de relecture comme outil d’édition, pas seulement comme validation finale. Après un premier plan, demandez :

• quelles exigences manquent dans la spec
• où les tâches ne sont pas actionnables
• où la personne qui implémente risque de se retrouver bloquée
• s’il y a une dérive du périmètre

Vous obtiendrez ainsi un deuxième jet bien plus solide qu’avec un simple prompt du type “improve the plan”.

Surveillez ces modes d’échec fréquents

La writing-plans skill est moins performante lorsque :

• la spec est incomplète
• les frontières entre fichiers sont supposées au lieu d’être ancrées dans le dépôt
• les tâches décrivent des résultats sans étapes d’implémentation
• les tests sont mentionnés sans être reliés aux changements de code
• un plan trop volumineux masque plusieurs livrables indépendants

Si vous constatez ces signes, révisez les entrées avant de mettre la faute sur la skill.

Ajoutez les contraintes qui changent réellement les choix d’implémentation

Parmi les contraintes utiles :

• les exigences de rétrocompatibilité
• les attentes de performance
• la sécurité des migrations
• l’ordre de déploiement
• les obligations de documentation
• les règles interdisant de nouvelles dépendances

Ces détails aident writing-plans for Requirements Planning à produire un plan adapté à votre environnement plutôt qu’un idéal générique.

Comparez le plan aux vrais besoins de transmission

Le bon test qualité est simple : un autre ingénieur, avec peu de contexte, pourrait-il implémenter à partir de ce document sans demander des clarifications répétées ? Si la réponse est non, améliorez le plan jusqu’à ce que les choix de fichiers, les frontières des tâches et les étapes de validation soient explicites.

Gardez un plan DRY et centré sur l’implémentation

Les consignes source insistent sur DRY, YAGNI, TDD et des commits fréquents. En pratique, cela signifie supprimer les tâches redondantes, éviter le travail spéculatif et privilégier des incréments qu’on peut coder et vérifier rapidement. Ces principes ont plus d’impact sur la qualité du résultat que le simple fait d’ajouter davantage de prose.