koleso-webestimator — Estimaciones calibradas para Umbraco / .N…

koleso-webestimator — Estimaciones calibradas para Umbraco / .NET

Estimaciones para trabajo web en Umbraco/.NET donde un agente de IA escribe el código y un humano lo revisa.

El hecho más importante detrás de esta habilidad, basado en ~300 tickets reales en 10 proyectos Umbraco:

La codificación rara vez es lo que hace que una estimación sea incorrecta. El trabajo grande estimado en días-persona de desarrollador superó en ~4×. Los tickets pequeños de "2–3 h" se subestimaron entre 2 y 3×. Ambos errores provienen del mismo lugar: el trabajo alrededor del código — despliegues, importaciones de uSync, pasos manuales por entorno, comportamiento real del CMS que las pruebas no pueden ver, rondas de QA y rondas de aclaración con el cliente — o se infló como "contingencia" o se omitió.

Por lo tanto, cada estimación aquí tiene dos libros:

1. Esfuerzo — horas que alguien realmente trabaja: codificación del agente + revisión, más los cubos que no se encogen.
2. Calendario — tiempo transcurrido, dominado por esperas de respuestas, ventanas de despliegue y colas de QA. Nunca se mezcla con el esfuerzo.

Archivos de referencia (leer cuando el paso lo indique):

• references/calibration.md — tasas de codificación a velocidad de agente y los cubos que no se encogen con tamaños predeterminados
• references/patterns.md — tiempos de referencia para tareas comunes de Umbraco / Razor / Vue / back-office
• references/platform-risks.md — comportamientos del CMS que cuestan rondas adicionales de despliegue-verificación
• references/honesty-rules.md — reglas obligatorias y umbrales de escalación
• references/output-format.md — el desglose interno y la respuesta para el cliente
• references/calibration-log.md — cómo registrar la estimación vs. lo real para que los números mejoren
• references/review-checklist.md — Modo Revisión: verificar una estimación que ya existe

---

Flujo de trabajo

Paso 0 — Encontrar la especificación y el plan, y decidir la base de la estimación

Antes de leer el código, buscar documentos de planificación sobre esta tarea. Buscar en:

• el repositorio: spec.md, SPEC.md, docs/spec/**, docs/specs/**, docs/plans/** (archivos nombrados *-plan.md, *-design.md, *-analysis.md, *-spec*.md), docs/handover/**, docs/adr/**, y cualquier archivo cuyo nombre contenga la clave del ticket o el slug de la funcionalidad;
• el ticket: su descripción, adjuntos y comentarios, y cualquier página de especificación enlazada desde él (ej. Confluence);
• estimaciones anteriores para el mismo ticket. Una estimación previa, una opción rechazada o una pregunta abierta cambia el número.

Luego elegir una base para la estimación e indicarla al inicio de la salida:

A. Estimación basada en plan. Existe una especificación y/o un plan de funcionalidad.

• Leer cada documento encontrado completamente, no solo los encabezados: requisitos, criterios de aceptación, fases, listas de archivos, preguntas abiertas, revisiones/desviaciones y decisiones de revisión.
• Estimar por fase del plan, usando las propias listas de archivos y pasos del plan como el esqueleto de las subtareas (Paso 4).
• Mapear cada requisito de la especificación / criterio de aceptación a una línea de la estimación. Listar cualquier requisito que ninguna fase cubra, y cualquier fase que ningún requisito solicite.
• Incluir las preguntas abiertas del plan en la lista de preguntas de la salida, cada una con su respuesta predeterminada.
• Verificar si el plan está desactualizado: comparar lo que nombra (archivos, alias, tipos de documento) con el código actual. Las líneas que ya no coinciden son una suposición que debe señalarse, no algo que valorar en silencio.
• Los rangos pueden ser más estrechos y la confianza más alta (ver references/honesty-rules.md).

B. Estimación rápida (alcance visible). No se encontró ninguna especificación ni plan.

• Indicarlo claramente al inicio: "No se encontró ninguna especificación ni plan de funcionalidad — esta es una estimación rápida del alcance visible." Listar dónde se buscó.
• Estimar solo a partir del texto del ticket y el código. Los rangos son más amplios y la confianza está limitada a Media.
• Listar lo que una especificación o plan tendría que resolver para que el número se consolide (las preguntas, las áreas afectadas que no se pudieron precisar).
• Ofrecer el siguiente paso: escribir un plan para el ticket, luego reestimar a partir de él (base A). Indicar en qué dirección esperas que se mueva el número basado en el plan, y por qué.

Si solo existe un documento parcial (ej. una especificación pero no un plan, o un plan para una fase diferente), usar la base A para lo que cubre y la base B para el resto, y etiquetar cada línea.

Además: si existe un registro de calibración (references/calibration-log.md explica dónde), leer las últimas entradas para tipos de trabajo similares.

Paso 1 — Detectar la pila tecnológica

Usar tus herramientas de búsqueda de archivos (no comandos específicos de shell — esto a menudo se ejecuta en Windows). Registrar:

Buscar	Te indica
*.csproj → versión de PackageReference Umbraco.Cms, TargetFramework	Mayor de Umbraco (10/13 = back-office AngularJS; 14+ = Bellissima Lit/TS) y versión de .NET
ModelsMode en appsettings*.json, carpeta de modelos generados	Modelos fuertemente tipados vs. IPublishedContent dinámico
Carpeta uSync/ + configuración de uSync (ExportOnSave, ImportOnFirstBoot, handlers deshabilitados)	Si los cambios de esquema necesitan una importación manual por entorno
App_Plugins/*/package.manifest vs umbraco-package.json + un proyecto Vite Client/	Tecnología de extensión de back-office
Archivos package.json: vue, nuxt, react, lit, jquery; ubicación de salida de compilación	Tipo de front-end y si su salida de compilación está confirmada
Configuración del compilador SCSS, CSS compilado confirmado, carpetas rtl/ltr	Pipeline de estilos y duplicación RTL
Idiomas en uSync Languages/, dir="rtl" en layouts	Número de culturas y costo de verificación RTL
Proyectos de prueba (xUnit/NUnit/Playwright), si Razor se compila en tiempo de compilación	Lo que una ejecución de pruebas verde realmente prueba
Composers/, Hangfire, configuración de índice Examine, migraciones, tablas DB personalizadas	Trabajos en segundo plano, búsqueda, datos personalizados
Archivos CI/despliegue, pistas de hosting (App Service, IIS, Docker)	Cuántos entornos y si los despliegues son manuales

Si no puedes leer el código base, indicarlo en la salida y ampliar todos los rangos 2–3× (ver reglas de honestidad).

Paso 2 — Leer el código más cercano a la tarea

Encontrar arte previo: el tipo de documento, parcial, controlador, isla Vue, elemento de back-office o importación más cercano existente que haga algo similar. Leer 2–4 de esos archivos. Verificar cada afirmación factual que harás en la estimación contra el código o el esquema uSync — ej., antes de escribir "ese campo no existe", buscar en las configuraciones de tipo de contenido. Una afirmación incorrecta cuesta una ronda completa de ida y vuelta con el cliente.

Paso 3 — Clasificar

Dimensión	Opciones
Tipo de trabajo	ver la tabla en references/calibration.md (tipo de documento/esquema, página Razor vs diseño, isla Vue, extensión de back-office, API/controlador, búsqueda, trabajo en segundo plano, importación de datos del cliente, integración de terceros, actualización, investigación, error)
Arte previo	Alto / Medio / Bajo
Claridad de la especificación	Clara / Parcial / Vaga
¿Escribe datos del CMS?	¿El código crea, guarda o publica contenido, bloques, medios o valores por cultura?
¿Front-end contra un diseño?	El trabajo de Figma verificado por píxeles activa una oleada de QA
Culturas × puntos de interrupción	ej. 3 idiomas (uno RTL) × escritorio/móvil
Entornos a los que debe llegar	Local, Dev, Stage, Prod — y qué pasos son manuales en cada uno
Parte externa	Contenido del cliente, una API de proveedor, un script de terceros, el pipeline de otro equipo

Paso 4 — Descomponer y dimensionar la codificación a velocidad de agente

Con un plan (base A), las fases del plan son los grupos de nivel superior y sus pasos/listas de archivos son las subtareas; no inventar un desglose diferente. Sin un plan (base B), construir el desglose tú mismo.

Dividir el trabajo en subtareas de 15 min – 2 h de trabajo del agente cada una. Dimensionarlas desde references/patterns.md y las tasas en references/calibration.md. Luego agregar tiempo de revisión (predeterminado 30–50% de la codificación del agente para código de producción; menos para pruebas y estilos).

Nunca dimensionar la codificación en días-persona de desarrollador y luego "agregar contingencia". Eso es el error de ~4×. Si una referencia que estás usando está en tiempo humano, convertirla con los multiplicadores en calibration.md.

Paso 5 — Agregar los cubos que no se encogen

De references/calibration.md → "Cubos que no se encogen". Agregar cada uno que aplique, como su propia línea, con su propio rango:

• Gastos de envío por entorno (compilación, despliegue, importación uSync, ediciones de diccionario/contenido, reguardado, verificación rápida)
• Rondas de verificación del CMS real cuando el código escribe datos del CMS o depende del comportamiento en tiempo de ejecución (platform-risks.md)
• Ejecución local del propietario + traspaso a QA
• Oleada de QA para trabajo de front-end contra un diseño (triage, correcciones, respuestas "no es un error")
• Matriz de verificación multilingüe / RTL
• Rondas de aclaración que esperas antes de que el alcance se fije
• Cola de actualización para actualizaciones de versión (ejecución de regresión, runbook, ensayo, correcciones posteriores al despliegue)
• Gastos generales de proceso si el equipo escribe planes, revisiones, documentos de verificación y traspasos por ticket

Aplicar el mínimo para tickets pequeños: cualquier ticket que deba llegar a un entorno compartido cuesta al menos los gastos de envío, incluso si el código es una línea.

Paso 6 — Tiempo de calendario

Listar de qué depende el tiempo transcurrido: preguntas abiertas al cliente, contenido que el cliente debe proporcionar, respuestas del proveedor, ventanas de despliegue, disponibilidad de QA. Dar el tiempo de calendario por separado (ej. "2–3 h de esfuerzo; realistamente 1–2 semanas transcurridas mientras se responden P1–P4").

Paso 7 — Autoverificación

1. Los rangos de las subtareas suman el total.
2. Ninguna subtarea individual supera las 2 h de trabajo del agente sin dividirse.
3. Se consideraron todos los cubos que no se encogen; los omitidos se omitieron intencionalmente (decir por qué).
4. No hay días-persona de desarrollador en ninguna parte; una unidad (horas) en todo momento.
5. Cada afirmación de "no existe" / "ya es compatible" se verificó en código o esquema.
6. La confianza es consistente con los modificadores en honesty-rules.md.
7. Total > 40 h → dividir en hitos y estimar cada uno.
8. La base (basada en plan / rápida / mixta) se indica al inicio. Con un plan, cada requisito de la especificación se asigna a una línea y cada fase del plan tiene precio. Sin uno, la salida lo indica y lista dónde se buscó.

Paso 8 — Salida

Usar references/output-format.md: un desglose interno para el desarrollador, y una respuesta para el cliente (tabla de rangos de horas, rango total, opciones con precio separado, suposiciones, preguntas numeradas cada una con la respuesta predeterminada que la estimación asume, riesgos, nota de calendario).

Luego registrar la estimación en el registro de calibración (references/calibration-log.md): automáticamente si las instrucciones del usuario nombran una ubicación de registro, de lo contrario ofrecer iniciar una. Registrar lo que la habilidad produjo y, una vez conocido, lo que realmente se envió al cliente.

---

Modos

Individual — el flujo de trabajo anterior.

Por lotes — para una especificación, épica o backlog: ejecutar los pasos 0–2 una vez, luego los pasos 3–7 por elemento (2–5 subtareas cada uno). Salida: una tabla (elemento, capa, rango de esfuerzo, tamaño, confianza, riesgo principal), suposiciones compartidas, dependencias cruzadas entre elementos, un orden sugerido y los cubos que no se encogen una vez para todo el lote donde sean realmente compartidos (un despliegue + una importación uSync pueden abarcar varios elementos; una oleada de QA por página, no por elemento).

Reestimación — después de que el cliente responda preguntas o cambie el alcance: mostrar solo el delta (líneas eliminadas, líneas añadidas, total revisado, qué pregunta lo causó). Los clientes responden las preguntas y luego piden que se confirme el número — hacer que el delta sea fácil de aprobar.

Revisión — cuando ya existe una estimación (en una especificación, un plan, un comentario de ticket) y se te pide verificarla: no reestimar desde cero. Seguir references/review-checklist.md:

• recopilar cada versión: el documento confirmado, la copia para el cliente, el código que cita;
• verificar la aritmética, luego si la base y la confianza coinciden con las reglas de honestidad;
• verificar la estructura (participación de revisión, cubos, cobertura de requisitos, opciones, valores predeterminados);
• reverificar los datos clave en el código y el esquema, y buscar los riesgos de la plataforma que omite.

Separar las correcciones internas de los cambios que el cliente debe ver. Recomendar volver a publicar un número solo si cambia.

Calibrar — cuando se te pida evaluar cómo resultaron las estimaciones ("¿qué tan precisos fuimos?", "calibrar la habilidad", "retrospectiva de las estimaciones"), o al final de un período de prueba:

1. Leer todo el registro de calibración. Para cada entrada cerrada, completar o verificar el valor real y su fuente (tiempo propio, registro de trabajo del ticket — señalar si es un total del equipo —, días activos en git); pedir los valores reales faltantes en lugar de adivinarlos.
2. Calcular proporciones por tipo de trabajo y por cubo, tanto para el número enviado al cliente como para el número de la habilidad.
3. Encontrar los errores sistemáticos: qué tipos de trabajo, qué cubos (oleada de QA, gastos de envío, rondas de verificación, aclaración), qué reglas (confianza, mínimo para tickets pequeños) fueron incorrectos, y dónde las anulaciones del humano fueron correctas.
4. Proponer ediciones concretas a references/calibration.md, patterns.md, platform-risks.md o las reglas, cada una vinculada a las filas del registro que la justifican. Por debajo de ~3 puntos de datos para un tipo: anotar, no cambiar.
5. Aplicar solo las ediciones que el usuario apruebe, agregar una entrada de registro de cambios con fecha al README de la habilidad, y agregar una línea al registro indicando qué calibración usan las próximas estimaciones.

Investigación — para tickets de "averiguar por qué…": acotar el tiempo (típicamente 0.25–1 h), indicar qué compra el tiempo acotado, y listar los resultados probables, incluyendo "no es un error", "ya está integrado" y "error del CMS aguas arriba — esperar la versión X". Estos resultados son comunes y baratos; no valorar una investigación como si una corrección fuera segura.