discuss

Skill de Discussão e Decomposição

Pré-requisito

RESEARCH.md deve existir e estar preenchido para o milestone atual.

Processo

Etapa 1: Resumo Executivo

Apresente ao humano um resumo do RESEARCH.md com:

• Stack e padrões encontrados
• Riscos com severidade (alto/médio/baixo)
• Restrições que afetam o planejamento

Etapa 2: Decisões Arquiteturais

Para cada decisão necessária:

• Apresente as opções com trade-offs claros
• Peça a decisão do humano — NÃO decida sozinho
• Registre em .spec/DECISIONS.md:

  ## DEC-0xx: [Título]
  - **Data:** YYYY-MM-DD
  - **Contexto:** [Por que essa decisão é necessária]
  - **Opções consideradas:**
    1. [Opção A] — [prós] / [contras]
    2. [Opção B] — [prós] / [contras]
  - **Decisão:** [O que foi decidido]
  - **Consequências:** [Impacto positivo e negativo]
  

• Registre contexto e preferências do usuário em CONTEXT.md

Etapa 3: Decomposição em Slices (Corte Vertical)

Cada slice deve ser um corte vertical completo — uma funcionalidade que pode ser demonstrada de ponta a ponta. Nunca corte por camada (ex: "fazer todo o banco", "fazer toda a API").

Como identificar slices:

1. Liste as funcionalidades do milestone do ponto de vista do USUÁRIO (ex: "fazer login", "ver perfil", "editar perfil")
2. Agrupe funcionalidades que compartilham infraestrutura base (ex: "login" e "cadastro" compartilham o modelo User e auth middleware)
3. Ordene por dependência: o que precisa existir antes?
4. Ordene por risco: slices arriscados devem vir cedo para falhar rápido
5. Cada slice deve ter 1-7 tasks

Critério de corte do slice:

• Entrega algo demonstrável? (pode mostrar para alguém e dizer "funciona")
• É independente o suficiente para ser testado isoladamente?
• Tem no máximo 7 tasks?

Se um slice tem mais de 7 tasks, ele é grande demais — divida.

Exemplo de corte ERRADO (por camada):

S01: Criar todos os modelos de banco ❌
S02: Criar todas as APIs ❌
S03: Criar todo o frontend ❌

Exemplo de corte CORRETO (vertical):

S01: Autenticação (modelo User + endpoint login + tela login) ✅
S02: Cadastro (endpoint registro + tela cadastro + validação) ✅
S03: Perfil (endpoint perfil + tela perfil + upload avatar) ✅

Etapa 4: Decomposição em Tasks (Uma Context Window)

Cada task deve caber em UMA context window. Use estes critérios para decidir onde cortar:

Regras de dimensionamento:

Critério	Se SIM → task separada
Modifica mais de 5-7 arquivos?	Divida
Envolve mais de 2 camadas (banco+API+frontend)?	Divida
Tem mais de 3 must-haves complexos?	Divida
Levaria mais de 30 min de um dev humano?	Divida
Precisa de pesquisa/exploração antes de implementar?	Divida em pesquisa + implementação

Padrão de decomposição típico para um slice:

T01: Fundação (tipos, interfaces, schemas)
  → Cria a base que as outras tasks vão usar
  → Artifact: src/types/user.ts com interface User exportada

T02: Camada de dados (modelo, repository, migração)
  → Implementa acesso a dados
  → Artifact: src/repositories/user.repository.ts
  → Link: importa User de src/types/user.ts

T03: Lógica de negócio (service, validação)
  → Implementa regras de negócio
  → Artifact: src/services/auth.service.ts
  → Link: importa UserRepository

T04: Camada de API (controller, rotas, middleware)
  → Expõe a funcionalidade via API
  → Artifact: src/routes/auth.routes.ts
  → Truth: POST /login retorna 200 com token

T05: Testes
  → Testa os paths críticos
  → Artifact: src/__tests__/auth.test.ts
  → Truth: testes passam com pnpm test

Tipos de must-haves:

Tipo	O que verifica	Exemplo
Artifact	Arquivo existe com implementação real	src/auth/login.ts com export function login()
Truth	Comportamento observável funciona	Usuário pode fazer login com email válido
Link	Integração entre módulos conectada	auth.service.ts importa UserRepository

Cada must-have DEVE ser verificável mecanicamente (pode checar com grep, teste, ou inspeção de arquivo).

Etapa 5: Apresentar Plano ao Humano

Antes de escrever os arquivos de plano, apresente a decomposição ao humano:

📋 PROPOSTA DE DECOMPOSIÇÃO — M001

🎯 Milestone: [Título]

📦 Slices (X total):

  S01: [Título] — Risco: baixo — 4 tasks
    T01: [título] — fundação (tipos e interfaces)
    T02: [título] — camada de dados
    T03: [título] — endpoints API
    T04: [título] — testes

  S02: [Título] — Risco: médio — 3 tasks (depende de S01)
    T01: [título] — ...
    T02: [título] — ...
    T03: [título] — ...

Total: X slices, Y tasks
Estimativa: cada task ≈ 1 sessão de /execute

Concorda com esta decomposição? Quer ajustar algo?

Aguarde aprovação antes de escrever os arquivos.

Etapa 6: Escrever Arquivos de Plano

Após aprovação do humano:

1. Crie ROADMAP.md:

# Roadmap — M001: [Título]

## Critérios de Sucesso
- [ ] [Critério verificável derivado dos requisitos]
- [ ] [Critério verificável derivado dos requisitos]

## Slices

- [ ] **S01: [Título]** — Risco: baixo — 4 tasks
  [Descrição]. Depende de: nenhum.

- [ ] **S02: [Título]** — Risco: médio — 3 tasks
  [Descrição]. Depende de: S01.

## Boundary Map

### S01 → S02
Produces:
- `src/types/user.ts` → interface User, interface Session
- `src/services/auth.ts` → generateToken(), verifyToken()

Consumes: nothing (first slice)

### S02 → S03
Produces:
- `src/routes/auth.routes.ts` → POST /login, POST /signup
- `src/middleware/auth.ts` → authMiddleware()

Consumes from S01:
- `src/services/auth.ts` → generateToken(), verifyToken()

O Boundary Map é OBRIGATÓRIO. Ele força o planejamento de como slices se conectam. Cada slice deve declarar o que PRODUZ (com file paths) e o que CONSOME.

2. Para cada slice, crie S0x/CONTEXT.md (scope do slice):

# S01: [Título] — Context

## Goal
[Uma frase: o que este slice entrega]

## Why this Slice
[Por que este slice esta sendo feito agora. O que desbloqueia.]

## Scope
### In Scope
- [item]

### Out of Scope
- [item]

## Integration Points
### Consumes
- `[file/artifact]` — [como é usado]

### Produces
- `[file/artifact]` — [o que fornece]

## Open Questions
- [questão] — [pensamento atual]

3. Para cada slice, crie S0x/PLAN.md:

# Plano — S01: [Título do Slice]

## Objetivo
[O que este slice entrega quando completo — demonstrável]

## Tasks

- [ ] **T01: [Título]**
  Must-haves:
  - Artifact: [caminho/arquivo.ts] com [o que deve conter]
  - Truth: [comportamento que deve funcionar]
  - Link: [import/integração que deve existir]
  Failure Modes (se aplicável):
  | Dependência | On error | On timeout |
  |---|---|---|
  | [dep] | [estratégia] | [estratégia] |
  Negative Tests (se aplicável):
  - Malformed: [input invalido a testar]
  - Error path: [cenario de erro a testar]

- [ ] **T02: [Título]**
  Must-haves:
  - Artifact: [caminho/arquivo.ts]
  - Truth: [comportamento]
  - Link: [integração com T01]

## Dependências
[Libs necessárias, slices anteriores, etc.]

## Notas de Implementação
[Decisões relevantes de DECISIONS.md que afetam este slice]

As seções Failure Modes e Negative Tests são OPCIONAIS — inclua apenas quando a task envolve dependências externas, APIs, async flows ou inputs de usuário. OMITA para tasks simples (tipos, schemas, config).

4. Opcionalmente, para tasks complexas, crie T0x-PLAN.md individual com mais detalhes.

Regras

• NÃO escreva código. Apenas planeje e alinhe decisões.
• SEMPRE apresente a decomposição ao humano antes de escrever arquivos.
• Cada task DEVE caber em uma context window.
• Cada must-have DEVE ser verificável mecanicamente.
• Slices são verticais (ponta a ponta), nunca horizontais (por camada).
• Se uma task modifica mais de 7 arquivos, divida.
• Se um slice tem mais de 7 tasks, divida o slice.
• O Boundary Map no ROADMAP.md é OBRIGATÓRIO.
• O S0x/CONTEXT.md é OBRIGATÓRIO para cada slice.