Escrevendo um Blueprint

1. Leia o Framework, não a sua memória

   eidos framework

   Tire três coisas dele: a tabela de propriedades, a convenção de nomes e as variants (variantes) da coleção de destino. Importa mesmo que você tenha escrito o Framework (a estrutura), porque ele deriva.

2. Escolha uma variant

   A padrão do grupo, senão a da coleção, a menos que você tenha um motivo; sem nenhuma, você nomeia uma. Comece leve: micro em software, sketch em book, note em research. Uma variant mais leve nunca é apontada por seções que só uma mais completa tem.

3. Monte o esqueleto

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

   O arquivo é nomeado pelo seu título na convenção do Framework. O frontmatter é gerado a partir das propriedades que se aplicam à coleção: new preenche o que pode (o id, o título, as datas, o grupo) e deixa o resto em branco.

   ---
   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
   ---

   Deixe em branco em vez de adivinhar

   Uma propriedade não preenchida é uma lacuna visível. Uma plausivelmente errada é uma mentira bem formatada. Este é o hábito mais importante quando um agente está ajudando; ele vai inferir um status com prazer se você deixar.

   Escreva summary como uma única linha simples: o que é este Blueprint (plano). É o que o índice mostra, ao pé da letra, e a única coisa que a maioria dos leitores vai ver da maioria dos Blueprints.

4. Escreva o corpo nesta ordem

   Não de cima para baixo:

   1. A seção de abertura, ## Intent na semente software: por que isto existe, o problema e quem o tem.
   2. Os non-goals, ## Out of Scope. Sim, em segundo. Por quê →
   3. Perguntas em aberto. Anotá-las cedo é a maior parte do valor de escrever o Blueprint cedo.
   4. Todo o resto.

   Mantenha a ordem do template (o modelo) no arquivo; esta é a ordem em que pensar.

5. Siga a rotulagem do template

   Onde um template pede rótulos, use-os. Na semente software cada requisito é REQ1:, REQ2:, começando em 1 em cada Blueprint e em ordem, para que uma revisão possa dizer “o REQ4 não é atendido” e outro Blueprint possa linkar para 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.

   Mantenha cada um curto e verificável. Um requisito que você não consegue verificar é uma esperança.

6. Omita o que não se aplica

   Deixe uma seção de fora em vez de vazia. Um título vazio afirma que você considerou algo e não encontrou nada; um ausente é honesto.

7. Verifique

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

Nomes

Uma convenção rege a raiz inteira, definida na instalação. Tudo o que uma pessoa lê na árvore a segue.

Convenção	Um arquivo de Blueprint	Uma pasta de grupo	Troca
kebab-case (padrão)	resume-playback.md	playback/	Legível em todo lugar, sem %20
TitleCase	ResumePlayback.md	Playback/	Sem espaços, com maiúsculas
Title Case	Resume Playback.md	Playback/	Se lê como prosa; %20 em todo link

Seja qual for a escolhida: .eidos/ é sempre minúsculo, README.md mantém o nome, um valor de agrupamento bate exatamente com a sua pasta, uma pasta que uma ferramenta possui é nomeada como a ferramenta diz, e nada dentro de uma pasta que o padrão não possui é submetido a ela.

Links

Um link markdown padrão, caminho relativo ao arquivo em que está, texto com o título humano, #heading para uma seção. Sem wikilinks, sem caminhos absolutos. No YAML, entre aspas: um [ inicial começa uma lista de outro modo.

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

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

Arquivos que não são Blueprints (uma imagem em assets/) são linkados ou incorporados do mesmo jeito. eidos check verifica que todo caminho resolve. Se o alvo ainda não tem Blueprint, nomeie-o simplesmente; um link para lugar nenhum parece resolvido.

Escreva como uma pessoa leria

As seções são um andaime, não um formulário. Dentro delas, use o que tornar o significado mais claro: subtítulos, tabelas, listas, um diagrama pequeno. Se se lê como texto de enchimento preenchido, remodele até que se leia como se alguém o tivesse escrito.

Um exemplo trabalhado

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.

Leia de novo a linha de Assumptions. “If it isn’t, the whole playback approach changes.” Essa frase é o Blueprint ganhando o seu lugar: nomeia o que invalidaria o resto, para que a próxima pessoa saiba o que verificar.

Próximo

• Delimitando com non-goals
• Trabalhando com agentes