wicttor/pwrl

PWRL Plan — Orchestrateur de Compétences Pures

Créez des plans d'implémentation durables qui peuvent être transmis pour exécution. Orchestre un pipeline déterministe de micro-compétences : périmètre → recherche → conception → génération. Aucune dépendance agent, aucun chemin de repli.

Objectif

Les plans capturent les décisions, la structure et l'approche avant l'exécution. Ils permettent :

• Un périmètre clair et des critères de succès
• Des risques et dépendances identifiés
• Des unités d'implémentation concrètes avec des critères d'acceptation
• La réutilisation des connaissances via les apprentissages associés
• La confiance que le travail ne déraillera pas

Workflow Principal : Pipeline en Quatre Phases

INPUT (description de la tâche)
  ↓
PHASE 1 : Périmètre (pwrl-plan-scope)
  → Rassembler le contexte, valider le domaine, amorcer les exigences
  → Sortie : artefact de contexte délimité
  ↓
PHASE 2 : Recherche (pwrl-plan-research)
  → Découvrir les modèles, identifier les risques, recommander des recherches externes
  → Sortie : artefact des résultats de recherche
  ↓
PHASE 3 : Conception (pwrl-plan-design)
  → Décomposer en unités, cartographier les dépendances, évaluer la complexité
  → Sortie : artefact de conception avec décomposition en unités
  ↓
PHASE 4 : Générer (pwrl-plan-generate)
  → Sélectionner le niveau, générer le plan, intégrer les apprentissages, sauvegarder dans docs/plans/
  → Sortie : document de plan final sauvegardé dans un fichier
  ↓
OUTPUT (fichier de plan prêt pour l'exécution)

Détails des Phases

Phase 1 : Périmètre (pwrl-plan-scope)

Objectif : Point d'entrée du workflow de planification. Rassemble le contexte, vérifie les plans et apprentissages existants, valide le domaine et retourne un objet de contexte délimité.

Micro-compétence : pwrl-plan-scope

Entrée :

• L'utilisateur fournit une description de tâche, un document d'exigences ou un objectif
• Une entrée vide invite l'utilisateur : "Que souhaitez-vous planifier ?"

Traitement :

1. Vérifier les plans existants dans docs/plans/ ; suggérer reprendre/réviser/archiver/supprimer/nouveau
2. Valider le domaine (logiciel vs. non-logiciel)
3. Amorcer le cadre du problème, le comportement attendu, les critères de succès
4. Rechercher dans docs/learnings/INDEX.md les apprentissages connexes
5. Rechercher dans docs/requirements/ et docs/brainstorms/ les documents correspondants
6. Confirmer le contexte avec l'utilisateur
7. Demander le mode d'interaction :
   • Détaillé : Interaction étape par étape à chaque phase (réviser, confirmer, ajuster)
   • Yolo : Automatisation complète de la Phase 1 à la Phase 4, confirmation finale uniquement
8. Générer l'artefact de périmètre avec mode_d_interaction

Sortie : Artefact de contexte délimité avec :

• Cadre du problème, comportement attendu, critères de succès
• Apprentissages connexes (pertinence ÉLEVÉE)
• Lacunes d'apprentissage identifiées
• Exigences trouvées
• mode_d_interaction (détaillé ou yolo)

Voir : pwrl-plan-scope/SKILL.md pour le workflow détaillé

Phase 2 : Recherche (pwrl-plan-research)

Objectif : Découvrir les modèles locaux, la pile technologique et les zones à haut risque. Recommander des recherches externes si nécessaire.

Micro-compétence : pwrl-plan-research

Entrée : Artefact de contexte délimité de la Phase 1

Traitement :

1. Détecter la pile technologique à partir de package.json, Dockerfile, la structure du codebase
2. Découvrir les modèles locaux (architecture, style asynchrone, tests, organisation)
3. Identifier les zones à haut risque (sécurité, performance, migrations, systèmes distribués, conformité)
4. Recommander des recherches externes pour les zones à haut risque (optionnel)
5. Intégrer les informations issues des apprentissages connexes
6. Compiler les résultats de recherche

Sortie : Artefact de recherche avec :

• Détection de la pile technologique
• Modèles locaux identifiés
• Zones de risque avec recommandations
• Résultats de recherche externe (si effectuée)
• Notes d'intégration des apprentissages

Voir : pwrl-plan-research/SKILL.md pour le workflow détaillé

Phase 3 : Conception (pwrl-plan-design)

Objectif : Décomposer le travail en unités d'implémentation, identifier les dépendances et les risques, évaluer la complexité.

Micro-compétence : pwrl-plan-design

Entrée : Contexte délimité + Résultats de recherche

Traitement :

1. Identifier les unités de travail à partir des critères de succès et des zones de risque
2. Cartographier les dépendances entre les unités (tri topologique)
3. Détecter les dépendances circulaires ; inviter à la refactorisation
4. Créer des unités d'atténuation des risques
5. Générer des diagrammes Mermaid pour les workflows complexes (5+ unités)
6. Évaluer la complexité (FAIBLE/MOYENNE/ÉLEVÉE)
7. Estimer l'effort
8. Confirmer la décomposition avec l'utilisateur

Sortie : Artefact de conception avec :

• Unités d'implémentation (U1, U2, ..., UX) avec scénarios de test et critères d'acceptation
• Graphe de dépendances et ordre topologique
• Atténuations des risques
• Diagrammes Mermaid (si complexe)
• Évaluation de complexité et estimation d'effort

Voir : pwrl-plan-design/SKILL.md pour le workflow détaillé

Phase 4 : Générer (pwrl-plan-generate)

Objectif : Sélectionner le niveau (Fast/Standard/Deep), générer le plan à l'aide du modèle de niveau, intégrer les apprentissages, sauvegarder dans docs/plans/.

Micro-compétence : pwrl-plan-generate

Entrée : Artefact de conception (Phase 3) + Artefact de périmètre (Phase 1)

Traitement :

1. Sélection automatique du niveau en fonction de la complexité/unités/effort ; inviter en cas d'ambiguïté
   • FAST : Complexité FAIBLE, 1-3 unités, <5 heures
   • STANDARD : Complexité MOYENNE, 4-8 unités, 5-20 heures
   • DEEP : Complexité ÉLEVÉE, 9+ unités, 20+ heures
2. Générer le plan à l'aide du modèle spécifique au niveau
3. Intégrer les 3-5 meilleurs apprentissages de pertinence ÉLEVÉE issus du périmètre
4. Générer un nom de fichier unique : YYYY-MM-DD-NNN-<slug>.md
5. Gérer les collisions de noms de fichiers (incrémenter la séquence ou mettre à jour l'existant)
6. Sauvegarder le plan dans docs/plans/

Sortie : Document de plan sauvegardé dans un fichier avec :

• Problème et périmètre
• Critères de succès
• Unités d'implémentation (niveau de détail spécifique au niveau)
• Analyse des risques (STANDARD/DEEP)
• Apprentissages connexes (STANDARD/DEEP)
• Lacunes d'apprentissage (DEEP)
• Notes de déploiement (STANDARD/DEEP)

Voir : pwrl-plan-generate/SKILL.md pour le workflow détaillé

Niveaux de Planification

Niveau	Idéal Pour	Fichiers	Risque	Temps
FAST	Corrections de bugs, petites retouches	1-3	FAIBLE	5-15 min
STANDARD	La plupart des fonctionnalités	4-8	MOYEN	30-45 min
DEEP	Architecture, sécurité, migrations	9+	ÉLEVÉ	1-2 heures

Voir references/planning-tiers.md pour les critères de décision complets et des exemples de modèles.

Principes Fondamentaux

• Pipeline Déterministe : Les phases s'exécutent toujours en séquence : périmètre → recherche → conception → génération (pas de branchement, pas de repli)
• Focus sur les Décisions : Capturer l'approche, la structure, les risques et le séquencement (pas de simulation de code)
• Taille Adaptée : Petites tâches → plans courts ; travail complexe → plus de structure
• Séparer Planification et Exécution : Ne pas simuler l'implémentation pendant la planification
• Soyez Concret : Utiliser des fichiers, composants et dépendances spécifiques
• Restez Portable : Utiliser uniquement des chemins relatifs au dépôt
• Artefacts Transparents : Chaque phase produit un artefact de sortie explicite pour la phase suivante

Gestion des Erreurs et Récupération

Philosophie : Échouer explicitement, pas silencieusement. Chaque phase a une gestion d'erreur claire avec des suggestions de récupération.

Erreurs de Phase 1 (Périmètre)

• Entrée Vide : Inviter l'utilisateur à fournir une description de tâche ; réessayer
• Domaine Non-Logiciel : Retourner une erreur ; suggérer un outil alternatif
• Entrée Ambiguë : Poser des questions de clarification ; amorcer avec les réponses de l'utilisateur
• Aucun Apprentissage/Exigence : Continuer (pas une erreur)

Récupération : L'utilisateur peut réessayer, fournir des clarifications ou abandonner

Erreurs de Phase 2 (Recherche)

• L'Analyse du Codebase Échoue : Continuer avec des informations minimales sur la pile technologique
• Zone à Haut Risque Identifiée : Recommander une recherche externe ; l'utilisateur peut approuver ou ignorer

Récupération : L'utilisateur peut approuver la recherche, l'ignorer ou enquêter manuellement

Erreurs de Phase 3 (Conception)

• Dépendance Circulaire Détectée : Signaler le chemin du cycle ; inviter l'utilisateur à refactoriser
• Trop d'Unités (15+) : Avertir de la complexité ; suggérer une consolidation
• Détails Insuffisants : Inviter à ajouter des scénarios de test ou à diviser les unités

Récupération : L'utilisateur peut refactoriser, consolider ou procéder en connaissance de cause

Erreurs de Phase 4 (Générer)

• Collision de Nom de Fichier : Proposer des options : mettre à jour, incrémenter ou annuler
• Sélection de Niveau Ambiguë : Inviter l'utilisateur à choisir le niveau
• Échec d'Écriture du Fichier : Vérifier les permissions/répertoire ; réessayer ou suggérer une sauvegarde manuelle

Récupération : L'utilisateur peut choisir une action ou sauvegarder manuellement

Résultats Clés

Chaque plan inclut (selon le niveau) :

• Problème et Périmètre : Cadre clair du problème et comportement attendu
• Critères de Succès : 1-3 conditions spécifiques pour l'achèvement
• Unités d'Implémentation : U-ID nommés avec dépendances, fichiers, approche et critères d'acceptation
• Apprentissages Connexes : Fichiers d'apprentissage liés avec notes d'applicabilité (STANDARD/DEEP)
• Lacunes d'Apprentissage : Zones nécessitant une documentation post-implémentation (DEEP)
• Sections Spécifiques au Niveau : Analyse des risques, alternatives, notes de déploiement (STANDARD/DEEP)

Méthode d'Interaction

• Utiliser l'extension ask_user_questions de la plateforme pour toutes les décisions
• Poser une question à la fois
• Utiliser des questions à choix multiples lorsque c'est possible
• Si l'entrée est vide, demander : "Que souhaitez-vous planifier ? Décrivez la tâche ou le projet."
• Fournir des suggestions de récupération claires en cas d'erreur

Architecture : Pas de Routage Agent

Différence par rapport à la version précédente :

Avant : La compétence détectait si l'agent était disponible, puis soit déléguait à l'agent SOIT exécutait un repli monolithique (deux chemins de code)

Après : La compétence appelle directement les micro-compétences en séquence — un seul pipeline déterministe, pas de branchement :

Orchestrateur pwrl-plan
├── 1. Appeler pwrl-plan-scope → obtenir l'artefact de périmètre
├── 2. Appeler pwrl-plan-research → obtenir l'artefact de recherche
├── 3. Appeler pwrl-plan-design → obtenir l'artefact de conception
└── 4. Appeler pwrl-plan-generate → sauvegarder le fichier de plan

Avantages :

• ✅ Plus simple à comprendre (un seul chemin de code)
• ✅ Plus facile à tester (pas de logique de branchement)
• ✅ Plus maintenable (micro-compétences testables indépendamment)
• ✅ Plus composable (micro-compétences réutilisables dans d'autres workflows)
• ✅ Meilleure gestion des erreurs (explicite à chaque phase)

Références des Micro-Compétences

• pwrl-plan-scope — Rassemblement du contexte et du périmètre
• pwrl-plan-research — Découverte de modèles et identification des risques
• pwrl-plan-design — Décomposition en unités et cartographie des dépendances
• pwrl-plan-generate — Génération du plan et création de fichiers

Documentation Associée

• references/planning-tiers.md — Définitions des niveaux et critères de décision
• docs/guides/micro-skill-patterns.md — Comment étendre avec de nouvelles micro-compétences
• docs/guides/skill-architecture-refactoring.md — Justification de la refactorisation

Tests et Validation

Couverture de test complète :

• 30+ tests pour pwrl-plan-scope (U1.1)
• 25+ tests pour pwrl-plan-research (U1.2)
• 35+ tests pour pwrl-plan-design (U1.3)
• 30+ tests pour pwrl-plan-generate (U1.4)
• 30+ tests d'intégration pour le pipeline d'orchestration complet

Rétrocompatibilité :

• Même comportement d'entrée/sortie que la version précédente
• Plans existants générés avec succès
• Aucun changement cassant pour les utilisateurs

Foire Aux Questions

Q : Que faire si une phase échoue ? Puis-je la sauter ou réessayer ?

R : Oui. Chaque phase a une gestion d'erreur explicite avec des suggestions de récupération. Vous pouvez réessayer, fournir des clarifications, modifier le périmètre ou abandonner. Pas d'échecs silencieux.

Q : Puis-je utiliser une seule micro-compétence (par ex., seulement générer à partir de la conception) ?

R : L'orchestrateur s'attend à appeler les quatre phases en séquence. Si vous souhaitez utiliser une seule micro-compétence, appelez-la directement par son nom : /pwrl-plan-scope, /pwrl-plan-design, etc.

Q : Pourquoi pas de routage agent ?

R : Les agents ajoutaient de la complexité sans valeur ajoutée. Le pipeline de micro-compétences est déterministe, testable et plus facile à comprendre. L'appel direct de compétences est plus simple et plus maintenable.

Q : Puis-je étendre cela pour d'autres workflows ?

R : Oui ! Les micro-compétences sont réutilisables. Par exemple, pwrl-work peut utiliser pwrl-plan-design pour la décomposition en unités. Voir docs/guides/micro-skill-patterns.md.

---

Statut : Pipeline de compétences pures (pas de routage agent) Version : 2.0 (refactorisé à partir d'une architecture dépendante de l'agent) Créé : 2026-06-11