koleso-webestimator

koleso-webestimator — estimations calibrées pour agent sur Umbraco / .NET

Estimations pour le travail web Umbraco/.NET lorsque un agent IA écrit le code et qu'un humain le révise.

Le fait le plus important derrière ce skill, issu d'environ 300 tickets réels sur 10 projets Umbraco :

Le codage est rarement ce qui rend une estimation erronée. Les gros travaux estimés en jours-homme développement ont été dépassés d'environ 4×. Les petits tickets « 2–3 h » ont été sous-estimés de 2–3×. Les deux erreurs viennent du même endroit : le travail autour du code — déploiements, imports uSync, étapes manuelles par environnement, comportements CMS réels que les tests ne peuvent pas voir, vagues de QA, et rounds de clarification client — était soit gonflé comme « marge de sécurité », soit omis.

Ainsi, chaque estimation ici comporte deux registres :

1. Effort — heures pendant lesquelles quelqu'un travaille réellement : codage agent + révision, plus les postes qui ne rétrécissent pas.
2. Calendaire — temps écoulé, dominé par l'attente de réponses, les fenêtres de déploiement et les files d'attente QA. Jamais mélangé à l'effort.

Fichiers de référence (à lire lorsque l'étape le dit) :

• references/calibration.md — taux de codage à vitesse agent et les postes non compressibles avec des tailles par défaut
• references/patterns.md — temps de référence pour les tâches courantes Umbraco / Razor / Vue / back-office
• references/platform-risks.md — comportements CMS qui coûtent des cycles supplémentaires de déploiement-vérification
• references/honesty-rules.md — règles obligatoires et seuils d'escalade
• references/output-format.md — la décomposition interne et la réponse orientée client
• references/calibration-log.md — comment enregistrer l'estimation par rapport au réel pour améliorer les chiffres
• references/review-checklist.md — Mode Révision : vérifier une estimation existante

---

Workflow

Étape 0 — Trouver le cahier des charges et le plan, et décider de la base de l'estimation

Avant de lire le code, recherchez les documents de planification concernant cette tâche. Regardez dans :

• le dépôt : spec.md, SPEC.md, docs/spec/**, docs/specs/**, docs/plans/** (fichiers nommés *-plan.md, *-design.md, *-analysis.md, *-spec*.md), docs/handover/**, docs/adr/**, et tout fichier dont le nom contient la clé du ticket ou le slug de la fonctionnalité ;
• le ticket : sa description, ses pièces jointes et commentaires, et toute page de spécification qui y est liée (ex. Confluence) ;
• les estimations précédentes pour le même ticket. Une estimation antérieure, une option rejetée ou une question ouverte modifie le chiffre.

Choisissez ensuite une base pour l'estimation et indiquez-la en haut de la sortie :

A. Estimation basée sur le plan. Un cahier des charges et/ou un plan de fonctionnalité existe.

• Lisez chaque document trouvé intégralement, pas seulement les titres : exigences, critères d'acceptation, phases, listes de fichiers, questions ouvertes, révisions/déviations et décisions de revue.
• Estimez par phase du plan, en utilisant les listes de fichiers et les étapes du plan comme squelette des sous-tâches (Étape 4).
• Mappez chaque exigence / critère d'acceptation à une ligne de l'estimation. Listez toute exigence qu'aucune phase ne couvre, et toute phase qu'aucune exigence ne demande.
• Reportez les questions ouvertes du plan dans la liste de questions de la sortie, chacune avec sa réponse par défaut.
• Vérifiez si le plan est obsolète : comparez ce qu'il nomme (fichiers, alias, doctypes) avec le code actuel. Les lignes qui ne correspondent plus sont une hypothèse à signaler, pas quelque chose à facturer silencieusement.
• Les fourchettes peuvent être plus étroites et la confiance plus élevée (voir references/honesty-rules.md).

B. Estimation rapide (périmètre visible). Aucun cahier des charges ni plan trouvé.

• Dites-le clairement en haut : « Aucun cahier des charges ou plan de fonctionnalité trouvé — ceci est une estimation rapide du périmètre visible. » Listez où vous avez cherché.
• Estimez à partir du texte du ticket et du code uniquement. Les fourchettes sont plus larges et la confiance est limitée à Moyenne.
• Listez ce qu'un cahier des charges ou un plan devrait résoudre pour que le chiffre se consolide (les questions, les zones affectées que vous n'avez pas pu cerner).
• Proposez l'étape suivante : rédiger un plan pour le ticket, puis ré-estimer à partir de celui-ci (base A). Dites dans quelle direction vous pensez que le chiffre basé sur le plan va évoluer, et pourquoi.

Si seul un document partiel existe (ex. un cahier des charges mais pas de plan, ou un plan pour une phase différente), utilisez la base A pour ce qu'il couvre et la base B pour le reste, et étiquetez chaque ligne.

Aussi : si un journal de calibration existe (references/calibration-log.md explique où), lisez les dernières entrées pour des types de travail similaires.

Étape 1 — Détecter la stack

Utilisez vos outils de recherche de fichiers (pas de commandes shell spécifiques — cela s'exécute souvent sur Windows). Enregistrez :

Recherchez	Vous indique
*.csproj → référence Umbraco.Cms PackageReference, TargetFramework	Version majeure d'Umbraco (10/13 = back-office AngularJS ; 14+ = Bellissima Lit/TS) et version .NET
ModelsMode dans appsettings*.json, dossier de modèles générés	Modèles fortement typés vs IPublishedContent dynamique
Dossier uSync/ + paramètres uSync (ExportOnSave, ImportOnFirstBoot, gestionnaires désactivés)	Si les modifications de schéma nécessitent une importation manuelle par environnement
App_Plugins/*/package.manifest vs umbraco-package.json + un projet Vite Client/	Technologie d'extension back-office
Fichiers package.json : vue, nuxt, react, lit, jquery ; emplacement de sortie de build	Type de front-end et si sa sortie de build est commitée
Configuration du compilateur SCSS, CSS compilé commité, dossiers rtl/ltr	Pipeline de style et duplication RTL
Langues dans uSync Languages/, dir="rtl" dans les layouts	Nombre de cultures et coût de vérification RTL
Projets de test (xUnit/NUnit/Playwright), si Razor est compilé à la build	Ce qu'une exécution de tests verte prouve réellement
Composers/, Hangfire, configuration d'index Examine, migrations, tables DB personnalisées	Tâches planifiées, recherche, données personnalisées
Fichiers CI/déploiement, indices d'hébergement (App Service, IIS, Docker)	Nombre d'environnements et si les déploiements sont manuels

Si vous ne pouvez pas lire la base de code, dites-le dans la sortie et élargissez chaque fourchette de 2–3× (voir les règles d'honnêteté).

Étape 2 — Lire le code le plus proche de la tâche

Trouvez l'art antérieur : le doctype, partiel, contrôleur, îlot Vue, élément back-office ou import le plus proche qui fait quelque chose de similaire. Lisez 2 à 4 de ces fichiers. Vérifiez chaque affirmation factuelle que vous ferez dans l'estimation par rapport au code ou au schéma uSync — par exemple, avant d'écrire « ce champ n'existe pas », recherchez les configurations de type de contenu. Une affirmation erronée coûte un aller-retour client complet.

Étape 3 — Classifier

Dimension	Options
Type de travail	voir le tableau dans references/calibration.md (doctype/schéma, page Razor vs design, îlot Vue, extension back-office, API/contrôleur, recherche, tâche planifiée, import de données client, intégration tierce, mise à niveau, investigation, bug)
Art antérieur	Élevé / Moyen / Faible
Clarté du cahier des charges	Clair / Partiel / Vague
Écrit des données CMS ?	Le code crée-t-il, sauvegarde-t-il ou publie-t-il du contenu, des blocs, des médias ou des valeurs par culture ?
Front-end par rapport à un design ?	Un travail Figma vérifié pixel par pixel déclenche une vague QA
Cultures × points de rupture	ex. 3 langues (dont une RTL) × desktop/mobile
Environnements à atteindre	Local, Dev, Stage, Prod — et quelles étapes sont manuelles sur chacun
Partie externe	Contenu client, une API fournisseur, un script tiers, le pipeline d'une autre équipe

Étape 4 — Décomposer et dimensionner le codage à vitesse agent

Avec un plan (base A), les phases du plan sont les groupes de niveau supérieur et ses étapes/listes de fichiers sont les sous-tâches ; n'inventez pas une décomposition différente. Sans plan (base B), construisez la décomposition vous-même.

Divisez le travail en sous-tâches de 15 min – 2 h de travail agent chacune. Dimensionnez-les à partir de references/patterns.md et des taux dans references/calibration.md. Ajoutez ensuite le temps de révision (par défaut 30–50 % du codage agent pour le code de production ; moins pour les tests et les styles).

Ne dimensionnez jamais le codage en jours-homme développement puis « ajoutez une marge de sécurité ». C'est le dépassement d'environ 4×. Si une référence que vous utilisez est en temps humain, convertissez-la avec les multiplicateurs dans calibration.md.

Étape 5 — Ajouter les postes qui ne rétrécissent pas

À partir de references/calibration.md → « Postes non compressibles ». Ajoutez chacun de ceux qui s'appliquent, sur sa propre ligne, avec sa propre fourchette :

• Frais d'expédition par environnement (build, déploiement, import uSync, modifications de dictionnaire/contenu, resauvegarde, vérification rapide)
• Cycles de vérification réelle du CMS lorsque le code écrit des données CMS ou dépend du comportement d'exécution (platform-risks.md)
• Exécution propriétaire/locale + remise QA
• Vague QA pour le travail front-end par rapport à un design (tri, correctifs, réponses « pas un bug »)
• Matrice de vérification multilingue / RTL
• Rounds de clarification que vous attendez avant que le périmètre soit fixé
• Queue de mise à niveau pour les mises à jour de version (exécution de régression, runbook, répétition, correctifs post-déploiement)
• Frais de processus si l'équipe rédige des plans, des revues, des documents de vérification et des remises par ticket

Appliquez le plancher des petits tickets : tout ticket qui doit atteindre un environnement partagé coûte au moins les frais d'expédition, même si le code est d'une seule ligne.

Étape 6 — Temps calendaire

Listez de quoi dépend le temps écoulé : questions ouvertes au client, contenu que le client doit fournir, répenses du fournisseur, fenêtres de déploiement, disponibilité QA. Donnez le temps calendaire séparément (ex. « 2–3 h d'effort ; realistiquement 1–2 semaines écoulées en attendant les réponses aux Q1–Q4 »).

Étape 7 — Auto-vérification

1. Les fourchettes des sous-tâches s'additionnent au total.
2. Aucune sous-tâche ne dépasse 2 h de travail agent sans être divisée.
3. Chaque poste non compressible a été considéré ; ceux qui sont sautés le sont intentionnellement (dites pourquoi).
4. Aucun jour-homme développement nulle part ; une seule unité (heures) partout.
5. Chaque affirmation « n'existe pas » / « déjà pris en charge » a été vérifiée dans le code ou le schéma.
6. La confiance est cohérente avec les modificateurs dans honesty-rules.md.
7. Total > 40 h → diviser en jalons et estimer chacun.
8. La base (basée sur le plan / rapide / mixte) est indiquée en haut. Avec un plan, chaque exigence du cahier des charges correspond à une ligne et chaque phase du plan est tarifée. Sans, la sortie le dit et liste où vous avez cherché.

Étape 8 — Sortie

Utilisez references/output-format.md : une décomposition interne pour le développeur, et une réponse orientée client (tableau de fourchettes horaires, fourchette totale, options séparément tarifées, hypothèses, questions numérotées chacune avec la réponse par défaut que l'estimation suppose, risques, note calendaire).

Ensuite, enregistrez l'estimation dans le journal de calibration (references/calibration-log.md) : automatiquement si les instructions de l'utilisateur nomment un emplacement de journal, sinon proposez d'en démarrer un. Enregistrez ce que le skill a produit et, une fois connu, ce qui a réellement été envoyé au client.

---

Modes

Unique — le workflow ci-dessus.

Batch — pour un cahier des charges, une épopée ou un backlog : exécutez les étapes 0–2 une fois, puis les étapes 3–7 par élément (2–5 sous-tâches chacun). Sortie : un tableau (élément, couche, fourchette d'effort, taille, confiance, risque principal), hypothèses partagées, dépendances inter-éléments, un ordre suggéré, et les postes non compressibles une fois pour l'ensemble du batch là où ils sont réellement partagés (un déploiement + un import uSync peut couvrir plusieurs éléments ; une vague QA par page, pas par élément).

Ré-estimation — après que le client a répondu aux questions ou que le périmètre a changé : montrez uniquement le delta (lignes supprimées, lignes ajoutées, total révisé, quelle question l'a causé). Les clients répondent aux questions puis demandent confirmation du chiffre — facilitez l'approbation du delta.

Révision — lorsqu'une estimation existe déjà (dans un cahier des charges, un plan, un commentaire de ticket) et qu'on vous demande de la vérifier : ne ré-estimez pas à partir de zéro. Suivez references/review-checklist.md :

• collectez chaque version : le document commité, la copie orientée client, le code qu'il cite ;
• vérifiez l'arithmétique, puis si la base et la confiance correspondent aux règles d'honnêteté ;
• vérifiez la structure (part de révision, postes, couverture des exigences, options, valeurs par défaut) ;
• revérifiez les faits clés dans le code et le schéma, et recherchez les risques plateforme qu'il manque.

Séparez les correctifs internes des changements que le client doit voir. Recommandez de republier un chiffre uniquement s'il change.

Calibration — lorsqu'on vous demande d'évaluer comment les estimations se sont déroulées (« à quel point étions-nous précis », « calibrer le skill », « rétrospective sur les estimations »), ou à la fin d'une période d'essai :

1. Lisez l'intégralité du journal de calibration. Pour chaque entrée fermée, remplissez ou vérifiez le réel et sa source (temps propre, worklog du ticket — notez s'il s'agit d'un total d'équipe —, jours actifs git) ; demandez les réels manquants au lieu de deviner.
2. Calculez les ratios par type de travail et par poste, pour le chiffre envoyé au client et pour le chiffre du skill.
3. Trouvez les erreurs systématiques : quels types de travail, quels postes (vague QA, frais d'expédition, cycles de vérification, rounds de clarification), quelles règles (confiance, plancher des petits tickets) étaient erronées, et où les surcharges humaines étaient justes.
4. Proposez des modifications concrètes à references/calibration.md, patterns.md, platform-risks.md ou aux règles, chacune liée aux lignes du journal qui la justifient. En dessous d'environ 3 points de données pour un type : notez, ne modifiez pas.
5. Appliquez uniquement les modifications que l'utilisateur approuve, ajoutez une entrée de journal de modification datée au README du skill, et ajoutez une ligne au journal indiquant quelle calibration les prochaines estimations utiliseront.

Investigation — pour les tickets « trouver pourquoi… » : limitez dans le temps (typiquement 0,25–1 h), indiquez ce que le timebox achète, et listez les résultats probables, y compris « pas un bug », « déjà intégré » et « bug CMS en amont — attendre la version X ». Ces résultats sont courants et peu coûteux ; ne tarifez pas une investigation comme si une correction était certaine.