vlaskos/brief-to-architecture

Análisis de ASR (Requisitos Arquitectónicamente Significativos)

Un brief no es una especificación. Es un montón de deseos, suposiciones y restricciones a medias; y enterrados dentro están los pocos requisitos que realmente decidirán la forma y el coste del sistema. Este skill encuentra esos requisitos, los precisa y los verifica entre sí antes de que alguien se comprometa con una estimación o un diseño.

Un requisito arquitectónicamente significativo (ASR) es un requisito con un efecto medible en la arquitectura: cumplirlo fuerza una elección estructural, restringe una tecnología, establece un nivel de calidad difícil de alcanzar, o interactúa con otros requisitos limitando tus opciones. La mayoría de los requisitos en un brief no son arquitectónicamente significativos. El trabajo consiste en separar los pocos vitales de los muchos, y explicar por qué cada uno importa.

La parte de atributos de calidad de este trabajo se basa en ISO/IEC 25010, el modelo internacional estándar de calidad de producto. Usar un conjunto estándar de características de calidad mantiene el análisis completo (verificas las mismas dimensiones cada vez) y le da a todos un vocabulario compartido. Consulta references/quality-model.md.

El proceso

Ejecuta un brief en seis pasos. Cada uno produce un artefacto que el siguiente utiliza.

1. Extraer, no transcribir. Lee la entrada original y extrae los requisitos reales, incluyendo aquellos expresados como funcionalidades, quejas o comentarios casuales. Una frase como "nuestro tráfico del Black Friday es 40 veces lo normal" no es una solicitud de funcionalidad; es un requisito de rendimiento y escalabilidad disfrazado. Interpreta. Consulta references/asr-framework.md para saber cómo reconocer lo que es arquitectónicamente significativo.

2. Clasificar. Ordena cada requisito extraído en uno de tres grupos:

   • Funcional — lo que el sistema debe hacer.
   • Atributo de calidad — qué tan bien debe hacerlo (rendimiento, fiabilidad, seguridad, mantenibilidad, …). Usa las características ISO/IEC 25010 para cubrir el mismo terreno cada vez — references/quality-model.md.
   • Restricción — un límite fijo y no negociable (una tecnología impuesta, una regulación, un plazo, un sistema existente). Las restricciones no están sujetas a diseño; moldean todo lo demás.

3. Afilar. Reescribe cada requisito significativo para que sea inequívoco y comprobable, y expresa su implicación arquitectónica — la consecuencia estructural de tomarlo en serio. Elimina las soluciones que el autor haya colado ("usa Kafka" es un mecanismo propuesto, no un requisito; el requisito es el rendimiento o desacoplamiento detrás de eso). Un requisito que no puedes probar, no puedes estimar.

4. Priorizar en dos ejes. No todos los ASR merecen la misma atención. Clasifica cada uno en:

   • Valor de negocio — cuánto importa el resultado al cliente.
   • Impacto arquitectónico — cuánto restringe el diseño y qué costoso es revertirlo. (El alto impacto se trata de irreversibilidad y radio de explosión, no de esfuerzo). Los requisitos que son altos en ambos son donde realmente se decide la arquitectura. Dedica tu análisis allí. Consulta references/scenarios-and-priorities.md.

5. Verificar viabilidad. Antes de diseñar nada, verifica que los requisitos de alta prioridad puedan coexistir. Los briefs más peligrosos son internamente contradictorios: un objetivo de latencia, un objetivo de consistencia y un techo de costes que no pueden ser ciertos a la vez. Consulta references/feasibility-check.md para un método concreto, incluyendo el aritmético para requisitos numéricos.

6. Especificar escenarios y elegir estrategias. Para los atributos de calidad de alta prioridad, escribe escenarios de calidad medibles (un desencadenante, las condiciones y una respuesta que se pueda medir), luego elige las estrategias de diseño que satisfarían cada uno, con su coste. Consulta references/scenarios-and-priorities.md y references/design-strategies.md.

Disciplina que hace el análisis fiable

• Detecta los olores. Los briefs tienen patrones de fallo recurrentes: superlativos vagos, suposiciones ocultas, números sin unidad ni fuente, requisitos que se contradicen. references/brief-smells.md es un catálogo de ellos y qué preguntar cuando los veas.
• Marca cada suposición. Cuando el brief calla y tú llenas un vacío, etiquétalo: ¿es un vacío rellenado (falta información, tú proporcionaste un valor por defecto), una interpretación (ambiguo, elegiste una lectura), o un acotamiento del alcance (excluiste deliberadamente algo)? Una estimación construida sobre suposiciones sin etiquetar es una adivinanza con traje.
• Termina con las preguntas que cambian la forma. El resultado de un buen análisis incluye las dos o tres preguntas cuyas respuestas cambiarían más la arquitectura. Esas son las que debería tratar la siguiente conversación con el cliente.
• Una estimación solo es defendible si el análisis que la sustenta también lo es. Por eso el análisis va primero: es lo que hace que el número que le das al cliente sea algo que puedas respaldar.

Cómo usar este skill

• Analizar un brief de principio a fin → ejecuta el proceso de seis pasos anterior.
• Decidir qué es arquitectónicamente significativo → references/asr-framework.md.
• Elegir y cubrir atributos de calidad → references/quality-model.md (ISO/IEC 25010).
• Escribir escenarios de calidad comprobables y priorizarlos → references/scenarios-and-priorities.md.
• Elegir enfoques de diseño por atributo de calidad → references/design-strategies.md.
• Detectar contradicciones y combinaciones imposibles → references/feasibility-check.md.
• Leer un brief críticamente → references/brief-smells.md.
• Dar forma al entregable escrito → references/output-template.md.