aTeering/skills

Ingeniero

Sintetiza el descubrimiento en dos artefactos duraderos: una especificación que /implement pueda ejecutar, y ADR para decisiones que vale la pena recordar.

Entrada: $ARGUMENTS.

Cero suposiciones silenciosas. Cada elección de diseño es tomada por el usuario o listada como una suposición. Esto incluye elecciones que parecen demasiado pequeñas para preguntar (librería, formato de error, nomenclatura, valores predeterminados, límites), lo que infieres del código base y tus propias recomendaciones. Lleva un Libro de Suposiciones (✅ confirmada por el usuario · ❓ no confirmada · ❌ rechazada) durante todo el proceso, y nunca escribas una elección no confirmada en una especificación o ADR como una decisión.

Proceso

1. Refinar. Si aún no hay un Resumen Refinado en esta sesión, ejecuta primero el proceso /refine (examen → criterios de aceptación). No continúes con preguntas abiertas que bloqueen el diseño. Si existe un resumen, lleva sus suposiciones ❓ a tu libro; resuélvelas antes de diseñar cualquier cosa que dependa de ellas.
2. Modelar. Ejecuta el proceso /domain-modelling para cualquier concepto nuevo o modificado y actualiza el documento de dominio. La especificación debe usar esos términos canónicos.
3. Explorar el código base. Identifica los módulos, interfaces, almacenes de datos y pruebas que toca el cambio. Observa los patrones existentes a seguir. Referencia rutas reales. Lo que el código hace hoy es evidencia, no intención: "seguir el patrón existente en src/x.ts" es en sí misma una elección que debe confirmarse con el usuario, registrada con su fuente.
4. Diseñar. Para cada decisión significativa, presenta 2–3 opciones con compensaciones y una recomendación; el usuario decide, y una recomendación solo cuenta cuando ellos la eligen explícitamente. Para elecciones más pequeñas, agrúpalas en una lista de confirmación en lugar de decidirlas tú mismo. Considera modelo de datos y migraciones, cambios de API/contrato, manejo de errores, seguridad, rendimiento, observabilidad, despliegue y reversión, y compatibilidad hacia atrás.
5. Registrar ADR. Una decisión merece un ADR si es difícil de revertir, afecta múltiples módulos, o un futuro ingeniero preguntaría "¿por qué lo hicimos así?". Escribe cada uno en docs/adr/NNNN-titulo-kebab.md (siguiente número libre, 4 dígitos) usando adr-template.md. Si un ADR reemplaza a otro, actualiza el estado del anterior. Marca un ADR como Aceptado solo cuando el usuario haya confirmado la decisión; de lo contrario, permanece Propuesto.
6. Escribir la especificación en docs/specs/<titulo-kebab>.md usando spec-template.md. Divide el trabajo en tareas pequeñas, ordenadas e independientemente comprobables — cada una con la(s) prueba(s) que la validan. Completa la sección de Suposiciones de la especificación desde el libro; cada declaración de diseño debe rastrearse hasta una decisión del usuario o aparecer allí como ❓.
7. Revisar con el usuario. Resume la especificación y los ADR, muestra los elementos ❓ abiertos, pide aprobación y ajusta. No establezcas la especificación como Aprobada mientras algún ❓ afecte una tarea, criterio de aceptación o ADR.

Reglas

• Respeta las convenciones existentes del proyecto si ya tiene carpetas o plantillas de especificaciones/ADR — úsalas en su lugar.
• La especificación describe qué y cómo verificar, con suficiente cómo para eliminar ambigüedad — no una implementación línea por línea.
• Cada criterio de aceptación debe mapearse al menos a una tarea y una prueba.
• Manténlo tan breve como lo permita el cambio.

Siguiente paso

Recomienda /handoff (para comenzar la implementación en una sesión nueva) o /implement docs/specs/<archivo>.md directamente.