Stage

Visão Geral

Stage é um documento de encadeamento para uma rodada de mudanças de engenharia — ele não substitui nenhum artefato de skill individual, mas sim registra o que cada skill produziu, como essas saídas se relacionam e a história completa desta rodada de mudanças.

Stage responde a quatro perguntas:

O que pretendíamos fazer? (MISSÃO + documento normativo)
Como o trabalho foi delegado com segurança? (Índice direto do Contract de Tarefa)
O que realmente fizemos? (Documento real + ADR)
Por que houve diferença? (Diferença normativo vs real + resumo de aprendizado)

                          STAGE.md
                   (Camada de encadeamento / Índice + Narrativa)
                          │
    ┌────────┬────────┬────┴────┬────────────┬────────┬────────┐
    │        │             │    │            │        │        │
  MISSÃO   Documento     Plano de   Contract     Documento  Verificação
  (Objetivo) Normativo   Implementação (Limites  Real       (Evidência)
                         (plan+todo)  de Delegação)(Resultado)
                                                │
                                              ADR
                                      (Obrigatório, pelo menos um por Stage)

Quando Usar

A criação do Stage é inteiramente decidida pelo usuário. Ela só ocorre quando o usuário solicita explicitamente, sem nenhuma condição de disparo automático.

O usuário normalmente inicia com:

"Criar Stage" / "Iniciar um Stage"
"Criar Stage para esta rodada de trabalho"
"Selar Stage" / "Seal Stage"
Após a saída de /plan, o usuário responde "sim" à pergunta "Precisa de um documento Stage?"

Cenários típicos de uso (para referência do usuário, não como regra de disparo):

Mudanças que abrangem várias tarefas e formam um todo lógico
Novas funcionalidades que atravessam vários módulos
Refatorações que alteram a estrutura interna sem modificar o comportamento
Cadeia completa de correção de defeitos em produção
Qualquer mudança que exija registro de decisões arquiteturais

Não é disparado automaticamente:

Tarefas isoladas ou mudanças mecânicas não criam Stage automaticamente
Atualizações puramente documentais não criam Stage automaticamente
O agente não decide por conta própria com base no número de tarefas ou na abrangência entre módulos — o usuário deve confirmar

delegated-task-contract não pode disparar automaticamente a criação de Stage mesmo quando precisa de um Stage pai; se ainda não houver Stage, ele deve parar e solicitar uma decisão explícita do usuário. A atribuição de diretório, índice unidirecional, sincronização de estado e restrições de selamento seguem uniformemente as Regras de Integração entre Stage e Task Contract.

Tipos de Stage

Tipo	Motivação	Critério de Sucesso	Normativo vs Real	Foco Documental
feat	Adicionar nova capacidade	Novo comportamento aparece e está em conformidade com as especificações	Diferenças são normais, devem ser registradas	spec + api-contract + api-doc
opt	Melhorar comportamento existente	Métricas atingem valores-alvo	Registrar brevemente a comparação de efeitos da otimização	Linha de base de desempenho + resultados de otimização
debug	Corrigir comportamento incorreto	Problema não se repete + testes de regressão cobrem o caminho da causa raiz	Normativo = Real (correção é o objetivo)	Fenômeno + causa raiz + estratégia de correção + medidas preventivas
refactor	Alterar estrutura interna sem mudar comportamento	Todos os comportamentos existentes permanecem inalterados, testes de regressão verdes	Normativo = Real é requisito rigoroso	Design arquitetural + descrição da mudança estrutural

Ciclo de Vida do Stage

Após saída de /plan       Durante a implementação         Após conclusão total     Na execução de /ship
     │                          │                            │                      │
     ▼                          ▼                            ▼                      ▼
  Criar esqueleto         Manter documentos e índice de    Selar STAGE.md          Verificar existência
  (MISSÃO +                Contract (estado, desvio,       (Restrições finais,     do Stage
   caminhos dos             resumo de evidência)            documentos reais,      (pre-launch
   documentos                                             ADR, análise de          checklist
   normativos,                                            diferenças,              itens bloqueantes)
   link do plano                                           resultados de
   de implementação)                                       verificação, resumo
                                                            de aprendizado)

Criação (Fase de Esqueleto)

Após /plan gerar tasks/plan.md e tasks/todo.md, o agente pergunta se o usuário precisa de um documento Stage. Após confirmação:

Criar diretório stages/<stage-id>/ (stage-id é um título curto em kebab-case)
Criar esqueleto STAGE.md com campos preenchidos:
- Tipo (feat | opt | debug | refactor)
- Estado definido como draft
- Decisor
- MISSÃO (extraída da especificação)
- Caminho do documento normativo (marcado como TODO)
- Link para plano de implementação (preenchido com tasks/plan.md e tasks/todo.md)
- Tabela de índice direto de Contracts de Tarefa (inicialmente vazia)
- Documento real (marcado como TODO — preencher após conclusão da implementação)
- ADR (marcado como TODO — pelo menos um por Stage, preencher após conclusão da implementação)
- Resultados de verificação (marcado como TODO)
Adicionar uma linha em stages/INDEX.md

Preenchimento (Fase de Construção)

Durante a implementação:

Tarefas comuns não exigem modificação do STAGE.md; mas a primeira gravação de um Contract, mudança de estado ou retorno de desvio/evidência deve ser sincronizada
Quando documentos normativos (spec, api-contract) são gerados, atualizar os links correspondentes e remover a marca TODO
Contract é indexado apenas pelo STAGE.md de forma direta; não adicionar campo Stage ou link de retorno no Contract
Desvios de Contract diferentes de none são sincronizados na tabela "Diferença Normativo vs Real", não deixando para lembrar no momento do selamento

Selamento (Após Conclusão)

Após todas as tarefas serem concluídas e verificadas, o agente lembra o usuário de selar. Após confirmação:

Comparar task-contract/ com a tabela de índice para confirmar que não há omissões, links quebrados ou desvios de estado
Confirmar que todos os estados do corpo dos Contracts são COMPLETED ou CANCELLED; qualquer DRAFT, READY ou BLOCKED_BY_ARCHITECTURE impede o selamento
Preencher links para documentos reais (api-doc, ADR)
Preencher a tabela de diferenças Normativo vs Real (incluindo coluna "Se deve atualizar retrospectivamente o documento normativo"), incorporando desvios significativos relatados pelos Contracts
Preencher resultados de verificação e link para Evidência Obrigatória do Contract
Extrair resumo de aprendizado ("Faça assim da próxima vez" e "Não faça assim da próxima vez")
Alterar estado para done
Atualizar a linha correspondente em stages/INDEX.md

Verificação (Antes do Lançamento)

O pre-launch checklist de /ship inclui:

"□ A mudança significativa tem um documento Stage correspondente?" — Se esta rodada de trabalho criou um Stage, isso é um item bloqueante

Template do Stage

Segue o template padrão para stages/<stage-id>/STAGE.md:

# Stage: [Título Curto]

**Tipo**: feat | opt | debug | refactor
**Data**: YYYY-MM-DD — YYYY-MM-DD
**Estado**: draft | in-progress | done | abandoned | superseded | split
**Decisor**: @username

---

## MISSÃO (Objetivo desta Rodada)

<!-- feat / opt / refactor usam o formato padrão da MISSÃO -->

- **Objetivo**: [Uma frase descrevendo o que esta rodada pretende alcançar]
- **Usuário**: [Quem se beneficiará]
- **Critério de Sucesso**: [Como saberemos que foi concluído — condições específicas e verificáveis]
- **Restrições**: [Limitações vinculantes — técnica, recursos, tempo]
- **Não Fazer**: [Itens explicitamente excluídos e o motivo]

<!-- debug substitui pela seguinte estrutura: -->
<!--
- **Fenômeno**: [O que o usuário fez, o que viu, o que deveria ter visto]
- **Impacto**: [Escopo do impacto, duração, risco de integridade dos dados]
- **Hipótese da Causa Raiz**: [Diagnóstico inicial — atualizar para causa raiz confirmada após implementação]
- **Estratégia de Correção**: [Plano de contenção + correção da causa raiz + medidas preventivas]
- **Critério de Sucesso**: [Problema não se repete, testes de regressão cobrem caminho da causa raiz, problemas similares têm verificação estática]
-->

→ Veja detalhes em [MISSION.md](./MISSION.md)

---

## Documento Normativo (Como Planejamos Fazer)

| Documento | Skill de Origem | Descrição |
|-----------|-----------------|-----------|
| [spec/xxx.md](./spec/xxx.md) | spec-driven-dev | Especificação funcional |
| [design/api-contract.md](./design/api-contract.md) | api-and-interface | Contrato de API |
| [design/xxx.md](./design/xxx.md) | — | [Descrição complementar] |

> Preencher antes do início da implementação. Se algum tipo de documento não for relevante nesta rodada, remover a linha correspondente.

---

## Plano de Implementação

| Documento | Skill de Origem | Descrição |
|-----------|-----------------|-----------|
| [tasks/plan.md](./tasks/plan.md) | planning-and-task | Plano técnico |
| [tasks/todo.md](./tasks/todo.md) | planning-and-task | Lista de tarefas atômicas |

---

## Contracts de Tarefa (Limites de Delegação para Execução)

> Apenas indexa delegações graváveis que exigem a barreira `delegated-task-contract`. O corpo do Contract, estado e Evidência Obrigatória são baseados no arquivo correspondente; esta tabela mantém apenas links diretos e resumos, sem escrever links de retorno do Stage no Contract.

| Tarefa | Contract | Estado | Desvio / Evidência |
|--------|----------|--------|--------------------|
| [ID da Tarefa] | [ID da Tarefa](./task-contract/TASK-XXX.md) | DRAFT \| READY \| BLOCKED_BY_ARCHITECTURE \| COMPLETED \| CANCELLED | [Bloqueio, desvio, evidência ou motivo de cancelamento; se não houver, escrever `—`] |

> Manter o cabeçalho da tabela e remover a linha de exemplo quando ainda não houver Contract. Sincronizar esta tabela na primeira gravação do Contract e a cada mudança de estado, desvio ou evidência.

---

## Documento Real (Como Realmente Ficou)

> Preencher esta seção após a conclusão da implementação.

| Documento | Skill de Origem | Descrição |
|-----------|-----------------|-----------|
| [docs/api/xxx.md](./docs/api/xxx.md) | documentation-and-adrs | Documentação real da API |
| [docs/adr/XXX-title.md](./docs/adr/XXX-title.md) | documentation-and-adrs | Registro de Decisão Arquitetural (obrigatório, pelo menos um por Stage) |

### ADR (Obrigatório)

Cada Stage **deve** produzir pelo menos um ADR. ADRs registram decisões arquiteturais críticas e seu contexto.

| ADR | Conteúdo da Decisão | Alternativas |
|-----|---------------------|--------------|
| [ADR-XXX](./docs/adr/XXX.md) | [Descrição da decisão em uma frase] | [Soluções rejeitadas e motivos] |

**Requisitos de Conteúdo do ADR:**
- Registrar "por que escolhemos A em vez de B"
- Listar alternativas consideradas e rejeitadas com os motivos
- Descrever as restrições e consequências da decisão
- Se a decisão estiver relacionada a um ADR existente, fazer referência explícita

**Foco do ADR por Tipo de Stage:**

| Tipo de Stage | Conteúdo Típico do ADR |
|---------------|------------------------|
| **feat** | Por que escolheu esta arquitetura/framework/protocolo; trade-offs no design do modelo de dados |
| **opt** | Por que escolheu esta estratégia de otimização; por que não outras opções (ex.: cache vs otimização de índice) |
| **debug** | Por que a causa raiz surgiu; por que escolheu esta solução de correção; design das medidas preventivas |
| **refactor** | Por que escolheu esta nova estrutura; por que não unificar certos casos limite; comparação entre estrutura antiga e nova |

---

## Diferença Normativo vs Real

> Preencher após a conclusão da implementação. Registrar cada desvio significativo entre o planejado e o real.

Quando o relatório de Evidência Obrigatória do Contract indicar um desvio diferente de `none`, sincronizar o desvio para esta tabela no momento da aceitação do Contract; não deixar o registro apenas no Contract.

| Diferença | Normativo (Planejado) | Real (Resultado) | Motivo | Se deve atualizar retrospectivamente o documento normativo |
|-----------|-----------------------|------------------|--------|-----------------------------------------------------------|
| [Breve descrição] | [O que foi planejado] | [O que realmente foi feito] | [Por que houve desvio] | Sim / Não |

**Explicação da coluna "Se deve atualizar retrospectivamente o documento normativo":**
- **Sim**: O desvio foi considerado uma direção de design correta e o spec ou api-contract foi retroativamente atualizado para ficar em conformidade com o real
- **Não**: O desvio foi um compromisso temporário ou comprometimento; o documento normativo permanece como está para referência em Stages futuros
- Todas as linhas marcadas como "Não" são entradas candidatas para o backlog da próxima rodada

---

## Resultados de Verificação

| Item de Verificação | Estado | Evidência |
|---------------------|--------|-----------|
| [Critério de Aceitação 1] | ✅ / ❌ | [Relatório de teste, dados de desempenho, captura de tela, etc.] |
| [Critério de Aceitação 2] | ✅ / ❌ | [Evidência] |
| Sem regressão | ✅ / ❌ | Link para execução de CI |

→ Veja detalhes em [VERIFY.md](./VERIFY.md)

---

## Resumo de Aprendizado

> Preencher no momento do selamento. No máximo duas frases.

- **Faça assim da próxima vez**: [O que foi feito certo nesta rodada — vale a pena reutilizar em outros Stages]
- **Não faça assim da próxima vez**: [O que foi feito errado nesta rodada — deve ser evitado, cuidado ou melhorado]

---

## Relacionamentos

- **Stage Anterior**: [STAGE-XXX](../stage-XXX/STAGE.md) (ou "Nenhum")
- **Próximo Planejado**: [Breve descrição, ou "Nenhum"]

Incrementos (Adicionados Após o Selamento)

Após o selamento do Stage (estado alterado para done), se pequenos problemas forem encontrados que precisem de reparo, mas não constituam um novo Stage, uma seção de incremento pode ser adicionada ao final do STAGE.md:

---

## Incremento 1 (2026-07-28)

- **Mudança**: [Breve descrição do que foi reparado]
- **Motivo**: [Por que este reparo foi necessário após o selamento]
- **Escopo do Impacto**: [Quais arquivos/módulos]

Ao adicionar incrementos:

O estado do Stage permanece done, não retorna para in-progress
Entradas de incremento são adicionadas em ordem cronológica
Se o reparo envolver uma nova decisão de ADR, adicionar à tabela de ADR no documento real e marcar com [Incremento 1]
Quando houver 3 ou mais incrementos acumulados, considerar se deve criar um novo Stage em vez de continuar adicionando

INDEX.md

stages/INDEX.md é a entrada de navegação para todos os Stages. É mantido na criação e selamento de cada Stage.

# Índice de Stages

| ID | Título | Tipo | Estado | Módulos Envolvidos | Data |
|----|--------|------|--------|---------------------|------|
| 001 | raft-election-optimization | opt | done | consensus, rpc | 2026-07-15 — 2026-07-17 |
| 002 | wal-checksum-verification | feat | done | storage, wal | 2026-07-18 — 2026-07-20 |
| 003 | replica-sync-refactor | refactor | done | replication, net | 2026-07-22 — 2026-07-23 |
| 004 | multi-az-placement | feat | abandoned | placement, scheduler | 2026-07-23 |

Regras de Manutenção:

Na criação do Stage, adicionar uma linha com estado draft
No selamento do Stage, atualizar o estado para done
Quando o estado do Stage muda para abandoned, superseded ou split, sincronizar imediatamente
Módulos Envolvidos lista os módulos/diretórios de alto nível afetados, facilitando a busca por módulo

Modelo de Estados

Estado	Significado	Quando Usar
`draft`	Esqueleto criado, implementação ainda não iniciada	Após a criação do Stage
`in-progress`	Implementação em andamento	Durante a implementação (uso opcional)
`done`	Concluído conforme planejado, selado	Todas as tarefas concluídas, verificações aprovadas, resumo de aprendizado escrito
`abandoned`	Abandonado no meio do caminho	Direção errada, requisitos cancelados, interrompido por prioridade mais alta
`superseded`	Substituído por outro Stage	O escopo do Stage-B engoliu o Stage-A
`split`	Dividido em vários Stages menores	Stage muito grande, dividido em sub-Stages independentes

Tratamento de abandoned:

Atualizar a seção MISSÃO, adicionando um parágrafo "Motivo do abandono"
Manter pelo menos um ADR na tabela, registrando "Por que não continuar"
Preencher o resumo de aprendizado normalmente — as lições de algo abandonado são muitas vezes mais valiosas que as de sucessos
Decidir se o código/documentação parcialmente concluídos do Stage abandonado devem ser revertidos; registrar no ADR
A seção "Próximo Planejado" em Relacionamentos muda para "Nenhum (abandonado)"

Tratamento de superseded:

Atualizar a seção MISSÃO, adicionando um parágrafo "Substituído por qual Stage e motivo"
Adicionar em Relacionamentos: "Substituído por: STAGE-XXX"
Alterar estado para superseded
Não adicionar mais incrementos no Stage substituído — todo trabalho futuro vai para o Stage que o substituiu

Tratamento de split:

Atualizar a seção MISSÃO, adicionando um parágrafo "Dividido em quais sub-Stages e motivo"
Adicionar em Relacionamentos: "Dividido em: STAGE-XXX, STAGE-YYY"
Alterar estado para split
O Stage original não recebe mais incrementos — todo trabalho vai para os sub-Stages

Estrutura de Diretórios

stages/
  INDEX.md                      ← Índice, uma linha por Stage
  001-raft-election-optimization/
    STAGE.md                    ← Documento de encadeamento do Stage
    MISSION.md                  ← Descrição detalhada do objetivo (opcional, recomendado para projetos complexos)
    spec/                       ← Normativo: especificação funcional
    design/                     ← Normativo: contrato de protocolo, layout de dados
    tasks/
      plan.md                   ← Plano de implementação
      todo.md                   ← Lista de tarefas
    task-contract/              ← Limites de delegação para execução, no mesmo nível que tasks/spec
      TASK-001.md
      TASK-002.md
    docs/
      protocol/                 ← Real: documentação do protocolo, interfaces RPC
      adr/                      ← Real: Registro de Decisão Arquitetural (obrigatório)
    verify/                     ← Evidências de verificação
      fault-injection-report.md
      consistency-check.txt
      perf-before-after.json
  002-wal-checksum/
    ...
    ...

Com exceção do caminho de atribuição do Task Contract, a estrutura de diretórios é um padrão recomendado. A restrição central é: STAGE.md deve existir, cada Stage deve conter pelo menos um ADR; se houver Task Contract, ele deve estar localizado em task-contract/ deste Stage e ser indexado diretamente por STAGE.md.

Interação com Outros Skills

Skill	Modo de Interação
spec-driven-development	A MISSÃO do Stage é extraída do Objective da especificação
planning-and-task-breakdown	Após a saída de `/plan`, o agente pergunta se deve criar o esqueleto do Stage
delegated-task-contract	Contract é salvo em `task-contract/` do Stage atual; `STAGE.md` indexa unidirecionalmente seu estado, desvio e evidência; o Contract não indexa o Stage
api-and-interface-design	Tanto os contratos de protocolo (gRPC/protobuf) no documento normativo quanto a documentação de interface no documento real são vinculados ao Stage
failure-injection-testing	Quando envolve tolerância a falhas e recuperação, o plano de injeção de falhas e o relatório do experimento de caos são vinculados ao documento real do Stage
consistency-and-durability-verification	Quando envolve armazenamento ou replicação de estado, o relatório de verificação de consistência/durabilidade é vinculado aos resultados de verificação do Stage
Fluxo de Implementação Nativo do Agente	Após todas as tarefas serem concluídas e verificadas, o agente lembra de selar o Stage
documentation-and-adrs	ADR é uma saída obrigatória do Stage; cada Stage deve ter pelo menos um
shipping-and-launch	`/ship` verifica se o Stage existe (se foi criado nesta rodada, é bloqueante)

Desculpas Racionais Comuns

Desculpa Racional	Realidade
"Esta mudança é muito pequena, não precisa de Stage"	Se a mudança é tão pequena que não precisa de Stage, provavelmente também não precisa de ADR. Mas o usuário já decidiu criar o Stage — confie no julgamento do usuário.
"O requisito é tão simples que o normativo e o real não terão diferenças"	Diferenças estão em toda parte — mesmo a mudança mais simples pode se desviar do plano durante a implementação. O valor central do Stage é exatamente registrar essas diferenças.
"Vou escrever o código primeiro, depois preencho o Stage"	O Stage antes do selamento é um diretório vivo, não precisa ser escrito de uma só vez. Mas preencher depois significa que a análise de diferenças depende da memória — e a memória não é confiável.
"Este não precisa de ADR"	Cada Stage tem pelo menos uma decisão que vale a pena registrar — mesmo que seja apenas "escolhemos a abordagem mais simples porque as restrições atuais não permitem uma solução mais complexa".
"Já foi `abandoned`, o resumo de aprendizado não tem sentido"	As lições de algo abandonado são muitas vezes mais valiosas que as de sucessos. Registrar "por que abandonamos" é pelo menos tão importante quanto registrar "por que tivemos sucesso".
"Marcar 'Não' na tabela de diferenças já é suficiente, não precisa explicar"	Cada linha da tabela de diferenças é uma entrada para decisões futuras. Marcar 'Não' diz ao próximo responsável: "aqui há dívida técnica, e ela foi deixada intencionalmente".
"INDEX.md pode ser preenchido depois"	O valor do INDEX.md cresce com o número de Stages — não parece importante no primeiro Stage, mas no décimo se torna essencial. Mantenha desde o início.

Bandeiras Vermelhas

STAGE.md foi criado mas a MISSÃO está vazia — o valor do esqueleto está na MISSÃO; um Stage sem objetivo é apenas um espaço reservado
O documento real tem documentação de API mas não tem ADR correspondente — viola a regra "pelo menos um ADR por Stage"
A tabela de diferenças está vazia mas o usuário mencionou desvios durante a implementação — diferenças não foram capturadas
O resumo de aprendizado diz "Nenhum" ou "Tudo correu bem" — todo Stage tem lições; se não encontrar, a reflexão não foi profunda o suficiente
Stage abandoned sem "Motivo do abandono" — perdeu a informação mais valiosa
Uma linha no INDEX.md permanece em estado draft por muito tempo — ou avance com a implementação, ou marque como abandoned; não deixe o esqueleto apodrecer
Seção de incrementos acumulou 3+ entradas sem considerar a divisão em um novo Stage — indica que o escopo desta rodada foi mal avaliado; reflita em vez de continuar adicionando
Campo decísor vazio — em colaboração multi-pessoa, isso quebra a cadeia de rastreamento de decisões
Arquivos em task-contract/ que não são indexados por STAGE.md, ou links de índice apontando para Contracts que não existem
Estado, desvio ou evidência do Contract mudaram, mas a tabela do Stage ainda mantém o resumo antigo
Contract tem link de retorno para STAGE.md, fazendo com que o relacionamento de pertencimento seja mantido bidirecionalmente
Ainda existem Contracts com estado DRAFT, READY ou BLOCKED_BY_ARCHITECTURE e o Stage está marcado como done

Verificação

Após criar o esqueleto do Stage:

stages/<stage-id>/STAGE.md existe
Tipo do Stage (feat | opt | debug | refactor) foi preenchido
Estado é draft
Decisor foi preenchido
MISSÃO foi preenchida (formato padrão ou formato debug, de acordo com o tipo)
Link do plano de implementação aponta para tasks/plan.md e tasks/todo.md
Seção "Contracts de Tarefa (Limites de Delegação para Execução)" e tabela de índice direto vazia foram criadas
Linha correspondente foi adicionada em stages/INDEX.md

Após selar o Stage:

13eholder/zflow

O que é zflow?

Perguntar na sua IA favorita

Documentação