Escribir un Blueprint

1. Lee el Framework, no tu memoria

   eidos framework

   Saca tres cosas de él: la tabla de propiedades, la convención de nombres y las variants (variantes) de la colección de destino. Importa aunque hayas escrito tú el Framework (el marco), porque va a la deriva.

2. Elige una variant

   La predeterminada de su grupo, y si no, la de la colección, salvo que tengas una razón; sin ninguna, nombras una. Empieza ligero: micro en software, sketch en book, note en research. Una variant más ligera nunca se señala por secciones que solo tiene una más completa.

3. Levanta la estructura

   eidos new specs "Resume Playback" --group playback --variant micro --summary "Returns a viewer to the exact second they stopped."

   El archivo se nombra por su título en la convención del Framework. El frontmatter se genera a partir de las propiedades que aplican a la colección: new rellena lo que puede (el id, el título, las fechas, el grupo) y deja el resto en blanco.

   ---
   id: resume-playback          # permanent, never renamed
   title: Resume Playback
   summary: Returns a viewer to the exact second they stopped.
   variant: micro
   date_created: 2026-06-20
   date_modified: 2026-06-20
   domain: playback             # matches the sub-folder exactly
   ---

   Déjalo en blanco antes que adivinar

   Una propiedad sin rellenar es un hueco visible. Una plausiblemente equivocada es una mentira con buen formato. Es el hábito más importante cuando un agente ayuda; inferirá un status encantado si se lo permites.

   Escribe summary como una sola línea llana: qué es este Blueprint (plano). Es lo que muestra el índice, literalmente, y lo único que la mayoría de lectores verá de la mayoría de Blueprints.

4. Escribe el cuerpo en este orden

   No de arriba abajo:

   1. La sección de apertura, ## Intent en la semilla software: por qué existe esto, el problema y quién lo tiene.
   2. Los non-goals, ## Out of Scope. Sí, en segundo lugar. Por qué →
   3. Preguntas abiertas. Anotarlas pronto es la mayor parte del valor de escribir el Blueprint pronto.
   4. Todo lo demás.

   Conserva el orden del template (la plantilla) en el archivo; este es el orden en que pensar.

5. Sigue el etiquetado del template

   Donde un template pida etiquetas, úsalas. En la semilla software cada requisito es REQ1:, REQ2:, empezando en 1 en cada Blueprint y en orden, para que una revisión pueda decir «el REQ4 no se cumple» y otro Blueprint pueda enlazar a watch-a-video.md#req4.

   ## Requirements
   
   - **REQ1:** A viewer opens a video and the player loads with its title, channel, and controls.
   - **REQ2:** The viewer can play, pause, and seek anywhere within the video.

   Mantén cada uno corto y comprobable. Un requisito que no puedes verificar es una esperanza.

6. Omite lo que no aplica

   Deja una sección fuera antes que vacía. Un encabezado vacío afirma que consideraste algo y no encontraste nada; uno ausente es honesto.

7. Compruébalo

   eidos check specs/playback/resume-playback.md
   eidos index

Nombres

Una convención rige toda la raíz, fijada al instalar. Todo lo que una persona lee en el árbol la sigue.

Convención	Un archivo de Blueprint	Una carpeta de grupo	A cambio
kebab-case (por defecto)	resume-playback.md	playback/	Legible en todas partes, sin %20
TitleCase	ResumePlayback.md	Playback/	Sin espacios, con mayúsculas
Title Case	Resume Playback.md	Playback/	Se lee como prosa; %20 en cada enlace

Elijas la que elijas: .eidos/ siempre va en minúsculas, README.md conserva su nombre, un valor de agrupación coincide exactamente con su carpeta, una carpeta que posee una herramienta se nombra como diga la herramienta, y nada dentro de una carpeta que el estándar no posee está sujeto a ella.

Enlaces

Un enlace markdown estándar, ruta relativa al archivo en que está, texto con el título humano, #heading para una sección. Sin wikilinks, sin rutas absolutas. En YAML, entre comillas: un [ inicial empieza una lista si no.

See [Resume Playback](resume-playback.md#intent) for the saved-position rules.

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

Los archivos que no son Blueprints (una imagen en assets/) se enlazan o incrustan de la misma manera. eidos check verifica que cada ruta resuelve. Si el destino todavía no tiene Blueprint, nómbralo llanamente; un enlace a ninguna parte parece resuelto.

Escríbelo como lo leería una persona

Las secciones son un andamio, no un formulario. Dentro de ellas, usa lo que haga el significado más claro: subencabezados, tablas, listas, un diagrama pequeño. Si se lee como texto de relleno completado, remodélalo hasta que se lea como si lo hubiera escrito alguien.

Un ejemplo resuelto

Blueprints/specs/playback/watch-a-video.md

---
id: watch-a-video
title: Watch a Video
summary: Play a video reliably, signed in or not, adapting to the connection.
variant: micro
domain: playback
status: Intake
depends_on:
  - "[Resume Playback](resume-playback.md)"
---

# Watch a Video

## Intent

A view is the core action of the whole product. If a video is slow to start
or stalls, the viewer leaves, so what "playing a video" means, and what a
viewer can count on, is the first thing to pin down.

### Assumptions

Adaptive-bitrate delivery over the CDN is available and affordable at launch
scale. If it isn't, the whole playback approach changes.

## Open Questions

- How long should a signed playback URL stay valid before it has to refresh?
- Does a view count on play start, or only after a watch-time threshold?

## Requirements

- **REQ1:** A viewer opens a video and the player loads with its title, channel, and controls.
- **REQ2:** A signed-out viewer who opens a shared link can still watch.
- **REQ3:** A stalled segment recovers by dropping quality rather than stopping playback.

## Out of Scope

- Picking up where the viewer left off, which [Resume Playback](resume-playback.md) holds.
- Comments and ratings on the watch page.
- Next-up recommendations once a video ends.

Vuelve a leer la línea de Assumptions. «If it isn’t, the whole playback approach changes.» Esa frase es el Blueprint ganándose su sitio: nombra lo que invalidaría el resto, para que la siguiente persona sepa qué comprobar.

Siguiente

• Acotar con non-goals
• Trabajar con agentes