Colecciones y Blueprints

Colecciones

Una colección es una carpeta de nivel superior con Blueprints repetidos que comparten un mismo shape (la plantilla del cuerpo). Un Framework declara cada una en Framework.md, y Eidos no nombra ninguna: specs, chapters, investigations, decisions son todas palabras de tu Framework.

Todo Framework debe declarar primero una colección de encuadre (los documentos sueltos que dicen qué es la cosa entera) y después al menos una colección de unidades.

Obligatoria como declaración, nunca como barrera

Un Framework que no declara colección de encuadre está incompleto, y una comprobación lo dice. Pero un frame (el encuadre) declarado y sin escribir es un hueco que hay que sacar a la luz, no un fallo. Eidos saca a la luz; no se niega. Más sobre los frames →

Agrupación

Una colección puede agrupar sus Blueprints en un nivel de subcarpetas, y no más. También puede declarar una propiedad que nombre esa agrupación: domain en la semilla software, part en book, strand en research.

Cuando lo hace, se siguen tres cosas:

• El valor de la propiedad coincide exactamente con el nombre de la carpeta, según la convención de nombres del Framework.
• Un valor desconocido avisa en lugar de bloquear. Las agrupaciones se acumulan; el validador no es el sitio donde discutirlas.
• El estándar nunca nombra la agrupación por ti. Es cosa de la colección.

• Directoriospecs/

  • index.md generado — nunca lo edites a mano
  • Directorioplayback/ un grupo

    • watch-a-video.md
    • resume-playback.md
  • Directoriochannels/ otro grupo

    • subscribe-to-a-channel.md

La hoja generada

Cada colección lleva un index.md que lista sus Blueprints, reconstruido entero por index. Cada línea es el summary de ese Blueprint, tal cual: un Blueprint sin él se señala, nunca se inventa. Más sobre las hojas generadas →

Blueprints

Un Blueprint (el plano) es un archivo markdown que define una unidad por completo. Dos partes:

---
id: resume-playback            ← frontmatter: the agreement
title: Resume Playback
summary: Returns a viewer to the exact second they stopped.
status: In Progress
domain: playback
---

# Resume Playback                ← body: the shape

## Intent
…

El frontmatter es el acuerdo; el cuerpo es orientación. Esa línea fija qué pasa cuando algo está mal. Las propiedades se comprueban contra el Schema del Framework. Las secciones del cuerpo son estructura recomendada: si falta una, se anota y se ofrece, nunca se rechaza.

El frontmatter se genera, no se teclea

Se genera por Blueprint a partir de las propiedades que aplican a la colección de ese Blueprint. Un Blueprint nuevo nace conforme, y una propiedad acotada a una colección nunca aterriza en otra donde no tiene sentido.

Un Blueprint, una unidad

La pregunta difícil siempre es «¿esto es un Blueprint o dos?». Eidos te da una prueba, y vive en el shape en lugar de en el estándar:

Un shape nombra su propia parte estable

Todo shape tiene una parte que se queda quieta y una parte que se mueve, y dice cuál es cuál. Si la parte estable cambia sustancialmente, pregúntate si esto no es otro Blueprint.

En la semilla software la parte estable es ## Intent. Así que: si cambia el porqué, tienes una spec nueva. Si solo cambian los comportamientos, tienes una edición. Esa es una prueba concreta que puedes aplicar en una revisión de código, que es de lo que se trata.

Los Blueprints no son tareas

La convención que más a menudo se intenta esquivar:

Sin campos de seguimiento de trabajo. Nada de sprint, estimate ni assignee: en el momento en que los añades, un Blueprint se convierte en una tarea y se pudre.

Conecta con un gestor de tareas mediante un enlace. Lo mismo vale para el cuerpo: una sección que describe cómo piensas construir algo captura intención; una sección que describe por dónde vas es seguimiento de trabajo, y muere en el mismo calendario que el ticket. Por qué importa →

Referenciar otros Blueprints

Referencia otros Blueprints con enlaces, no con nombres sueltos, tanto en la prosa como en las propiedades. El id sigue siendo la identidad permanente, detrás del enlace.

depends_on:
  - "[Watch a Video](../playback/watch-a-video.md)"

Entrecomíllalos en YAML: si no, un [ inicial empieza una lista. Y solo una raíz en Title Case lleva %20; las otras dos convenciones no tienen espacios.

Si un destino todavía no tiene Blueprint, nómbralo llanamente en lugar de fabricar un enlace.

Las dos maneras en que un Blueprint puede salir mal

Vale la pena nombrar las dos, porque fallan de forma distinta.

Se lee como un formulario. Todas las secciones presentes, todas vacías de criterio. El estándar es explícito: si un Blueprint se lee como una plantilla rellenada, remodélalo hasta que se lea como algo que escribió alguien. Deja fuera una sección cuando de verdad no aplica, en lugar de dejarla llena de nada.

No tiene no-objetivos. La sección Out of Scope es en la que más se apoya el estándar, porque es donde de verdad se sostiene el alcance, y es la primera sección que se vacía en silencio cuando nadie es dueño de la raíz. Por qué →

Siguiente

• Shapes y flavors: la plantilla del cuerpo.
• Schema: el contrato de frontmatter.
• Escribir un Blueprint: de principio a fin.