Shapes y flavors

Un shape es una plantilla de cuerpo

Un shape (la plantilla del cuerpo) son las secciones que lleva un Blueprint: en orden, bajo nombres fijos, cada una con su orientación. Nunca describe el frontmatter: eso se genera a partir del Schema.

Un archivo por shape, en _eidos/shapes/, con el nombre <kind>.<flavor>.md, en minúscula y con puntos.

• Directorio_eidos/shapes/

  • spec.full.md la colección specs, flavor full
  • spec.micro.md la colección specs, flavor micro
  • frame.architecture.md la colección de encuadre, un archivo por tipo de frame
  • frame.audience.md

Flavors

Los shapes de una colección son variantes de una misma familia, y cada variante es un flavor (la variante). Una colección declara uno o más y marca uno por defecto.

Lo que flexiona es qué secciones aparecen y qué flavor usa un Blueprint, nunca su orden ni sus nombres dentro de un flavor.

Aquí está la misma colección en dos flavors, de la semilla software:

spec.micro	spec.full
## Intent	## Intent
### Assumptions	### Assumptions
—	### Implementation Notes
## Open Questions	## Open Questions
## Behaviors & Acceptance Criteria	## Behaviors & Acceptance Criteria
—	### Functional · ### Performance · ### Design · ### External interface · ### Quality attributes
## Out of Scope	## Out of Scope
—	## Dependencies
—	## Testing
—	## Constraints & Decisions

micro es la spec más pequeña que vale la pena escribir: por qué existe, qué obtienes y qué no va a hacer. Es un punto de partida que crece hasta full a medida que la unidad se asienta.

Fíjate en lo que micro conserva incluso en su mínima expresión: Intent, Open Questions, Acceptance Criteria y Out of Scope. Esas cuatro son lo que es una spec. Testing y Dependencies pueden esperar; el alcance no.

Declarar qué flavor usa un Blueprint

Un Blueprint que no está en el flavor por defecto lo registra en el frontmatter:

flavor: micro

Si falta, se entiende el flavor por defecto de la colección. El por defecto es también lo que se genera al crear el archivo.

Un flavor más ligero no es un Blueprint peor

A un Blueprint en un flavor más ligero nunca se le reprochan las secciones que solo lleva uno más completo. La validación comprueba un Blueprint contra el flavor que nombra, no contra el más completo disponible.

Hacer crecer un Blueprint

El camino previsto, y la razón misma de que existan los flavors:

1. Escríbelo como micro pronto, cuando hay más pregunta que respuesta.
2. Añade las secciones del flavor más completo a medida que se ganan su sitio: dependencias reales, una historia real de pruebas, una decisión tomada de verdad.
3. Pon flavor: full (o elimina la propiedad) cuando ya haya crecido hasta ahí.

No generes el shape completo y lo dejes vacío

Una spec full con cinco encabezados vacíos es peor que una spec micro completa, porque da a entender que consideraste cosas que no consideraste. Debe leerse como algo que escribió alguien.

Dos convenciones que sostienen los shapes

Una familia de shapes por colección

El shape nunca se bifurca por categoría. Si la mitad de tus specs necesitan secciones distintas, eso o es un flavor o es otra colección, no un segundo shape colado dentro de la misma. Esto es lo que mantiene una colección legible como conjunto.

Un shape documenta sus propias convenciones

Los nombres de sección, su orden y significado, y cualquier etiquetado que pida el shape viven en el archivo del shape. El estándar gobierna colecciones, shapes, flavors y propiedades; nunca gobierna una sección.

Esa segunda regla es la razón de que no encuentres ## Intent ni ## Out of Scope en ningún sitio de EIDOS.md. Esas son palabras de la semilla software. book abre un capítulo de otra manera; research abre una investigación de otra distinta. La maquinaria es idéntica.

Qué aspecto tiene un archivo de shape

_eidos/shapes/spec.micro.md

<!--
The Spec shape — micro flavor. The smallest spec worth writing: why it exists,
what you're getting, and what it will not do. Grows into spec.full.md.
Keep the order and headings; the italic prompts are guidance — delete them
as you fill each section in.
-->

# {{title}}

## Intent

_Why this exists — the problem and who has it. This is the stable part: if
Intent changes substantially, you probably have a different spec._

### Assumptions

_What you're taking as given, not yet confirmed._

## Open Questions

_What you don't yet know and still need answered. Kept high, right after
Intent, so uncertainty is seen rather than buried._

## Behaviors & Acceptance Criteria

_What it does, as observable outcomes. If a behavior isn't listed here, it
isn't promised. Label each **AC1:**, **AC2:**, … Keep each short and checkable._

- **AC1:** <!-- the first observable outcome -->

## Out of Scope

_Explicit non-goals — the section the standard leans on hardest. It's the
first thing to write, not the last._

Tres cosas en las que fijarse, porque son convenciones que vale la pena copiar en tus propios shapes:

• El comentario HTML de arriba dice para qué sirve el flavor y en qué crece. Es orientación para quien abra el archivo después.
• {{title}} es el único marcador de posición; todo lo demás es estructura real.
• Los avisos en cursiva son instrucciones que hay que borrar según rellenas cada sección. No son contenido.

Escribir dentro de un shape

Mantén el orden y los nombres del shape. Más allá de eso, escríbelo como lo leería una persona: subencabezados, tablas, listas y diagramas pequeños allí donde aclaren el sentido.

Donde un shape pida etiquetado (AC1:, AC2: …), síguelo: mantén cada afirmación comprobable corta y observable, y empuja el detalle de apoyo a una tabla o subsección a la que apunte.

Déjala fuera, no la dejes vacía

Omite una sección que de verdad no aplique. Un encabezado vacío afirma que pensaste algo y no encontraste nada; uno ausente es honesto.

Los documentos de nivel superior no tienen shape

Un documento de nivel superior (un Roadmap, una Visión, el canvas generado) es único: se rellena una vez y se edita en el sitio. No recibe shape, ni flavors, ni validación.

Un shape se gana su sitio siendo estampado otra vez. Un documento escrito una sola vez no necesita molde.

Esa es también la única diferencia entre un frame y un documento de nivel superior. Los dos son prosa suelta, revisada en el sitio. Pero un frame es un Blueprint de colección: sigue un shape, lleva el contrato de frontmatter y se valida. Más sobre los frames →

Siguiente

• Schema
• Dar forma a tu Framework: añadir un flavor.