name: specify description: 'Convert a natural-language feature description into SDD spec (user stories, FRs, success criteria). Triggers: "specify", "criar spec", "nova feature", "feature spec". Skip for refining an existing spec (clarify).' argument-hint: "[descricao da feature em linguagem natural]" allowed-tools: - Read - Write - Edit - Glob - Grep - Bash

Skill: Especificar Feature (SDD)¶

Transforme uma descricao em linguagem natural em uma feature spec completa seguindo o formato Spec-Driven Development. Foco no QUE e POR QUE — nunca no COMO implementar.

Pre-requisitos¶

Opcional mas recomendado: - /briefing — contextualiza a feature dentro do projeto - /constitution — principios ajudam a calibrar escopo e padroes de qualidade

Sem esses, a skill funciona mas pode precisar de mais [NEEDS CLARIFICATION].

Proximos passos¶

/clarify — resolver ambiguidades da spec (se houver [NEEDS CLARIFICATION])
/plan — gerar plano tecnico de implementacao
/checklist — validar qualidade dos requisitos antes de implementar

Argumentos¶

$ARGUMENTS

Leitura de artefatos foundational (briefing + constitution)¶

Antes de ler docs/briefing.md (ou o legado docs/01-briefing-discovery/briefing.md) ou docs/constitution.md direto do disco, verifique se ha cache valido populado pelo agente-00c ou feature-00c. Aditivo — se nao houver cache, leia direto do disco conforme comportamento padrao (FR-CACHE-014).

Detectar agente ativo: variavel AGENTE_00C_STATE_DIR setada, OU <projeto-alvo>/.claude/agente-00c-state/state.json existente, OU <projeto-alvo>/.claude/feature-00c-state/<short>/state.json.

Se ativo, tente consumir o resumo via Bash:

~/.claude/skills/agente-00c-runtime/scripts/state-cache.sh get-resumo \
  --state-dir "$SD" --artifact briefing

Exit 0 + stdout nao-vazio: use o resumo como conteudo.
Exit 1: cache miss (campo ausente, estrategia=passthrough, drift detectado) — caia em leitura direta.
Exit 2: erro fatal (state.json corrompido) — aborte com diagnostico do stderr.

Mesmo protocolo para --artifact constitution.

Apos consumo (hit ou miss), registre metrica via:

~/.claude/skills/agente-00c-runtime/scripts/state-cache.sh metrics-bump \
  --state-dir "$SD" --tipo <hit|miss-drift|miss-disabled> \
  [--chars-economizados N]

onde N = source_chars - resumo_chars quando hit, ou 0 caso contrario.

Standalone (sem state.json): leia direto do disco. Comportamento identico a versao pre-cache.

Spec: docs/specs/_archived/agente-00c-artifact-cache/spec.md FR-CACHE-008.

FLUXO DE EXECUCAO¶

0. TRIAGEM         Classificar pedido e confirmar relevancia do SDD
     |
1. ANALISE         Parsear descricao e extrair conceitos
     |
2. ESTRUTURA       Criar diretorio e gerar short name
     |
3. ESPECIFICACAO   Preencher template com conteudo concreto
     |
4. VALIDACAO       Checar qualidade contra criterios internos
     |
5. CLARIFICACAO    Resolver ambiguidades criticas com o usuario
     |
6. SALVAMENTO      Salvar e reportar proximos passos

ETAPA 0: TRIAGEM (OBRIGATORIA ANTES DE PROSSEGUIR)¶

Antes de gerar qualquer artefato, classifique o pedido e valide com o usuario se o fluxo SDD completo faz sentido para o escopo. O fluxo SDD (spec → clarify → plan → tasks) tem custo real e nem todo pedido justifica esse overhead.

0.0 Atalho de modo autonomo (agente-00c / feature-00c)¶

A confirmacao interativa de 0.1-0.3 pressupoe um usuario presente para responder o menu. Em execucao autonoma nao ha — e a triagem JA aconteceu: o operador decidiu rodar a pipeline SDD completa quando invocou /agente-00c ou /feature-00c.

Detectar execucao autonoma ativa — mesmos sinais da secao "Leitura de artefatos foundational", com um refinamento para os state.json em disco: exigir status ATIVO (um state antigo/concluido no repo NAO pode pular a triagem de uma invocacao manual):
AGENTE_00C_STATE_DIR setada; OU
<projeto-alvo>/.claude/agente-00c-state/state.json com .execution.status em {em_andamento, aguardando_humano}; OU
<projeto-alvo>/.claude/feature-00c-state/<short>/state.json com .execution.status em {em_andamento, aguardando_humano}.
Se detectado: a invocacao pelo orquestrador pai VALE como a confirmacao explicita exigida em 0.3 (equivalente a escolher a opcao 2, "Criar feature SDD completa"). NAO apresentar o menu nem aguardar resposta. Executar 0.1 mesmo assim (classificacao e barata e util como auditoria), registrar o pressuposto em UMA linha no output e prosseguir direto a ETAPA 1:

Triagem 0.0: modo autonomo detectado (<sinal>) — confirmacao herdada
da invocacao do orquestrador; classificacao: <categoria>.

Se a classificacao 0.1 resultar em Bugfix ou Refactor, NAO abortar nem trocar de skill: a decisao de rodar a pipeline foi do operador. Apenas registrar a divergencia na mesma linha (classificacao: bugfix — divergencia registrada para auditoria) para aparecer no sumario da onda.

Reabertura da PROPRIA feature — alem da confirmacao de 0.3, checar tambem se ha contexto de reabertura no state da execucao corrente: campo .previous_round preenchido (nao-nulo), gravado pelo passo 3'' do fluxo /feature-00c --reopen (docs/specs/feature-reopen/contracts/reopen-flow.md):

_PREV=$(~/.claude/skills/agente-00c-runtime/scripts/state-rw.sh get \
  --state-dir "$SD" --field '.previous_round' 2>/dev/null) || _PREV="null"

Se _PREV for diferente de null/vazio, a decisao da secao 0.4 ("Atualizar spec existente vs abrir feature nova") TAMBEM ja foi tomada — no gate humano do passo 6.c da reabertura o operador confirmou explicitamente reabrir, que equivale a escolher "atualizar spec existente" em 0.4 aplicado a PROPRIA feature que esta sendo reaberta (nunca uma comparacao com outras specs do portfolio). Pular 0.4 sem reperguntar; a spec-alvo e sempre docs/specs/<short>/spec.md da propria feature. Registrar em uma linha:

Triagem 0.4: contexto de reabertura detectado (.previous_round presente)
— decisao herdada do gate 6.c (reabrir); tratando como "atualizar spec
existente" da propria feature, sem reperguntar.

Nesse caso, o incremento MUST ser aplicado como acrescimo na spec EXISTENTE, nunca como spec nova (FR-014 de feature-reopen) — seguir o procedimento descrito em "0.5 Modo de incremento (reabertura)" logo apos 0.4, em vez de ETAPA 1-3 normais.

Sem esse campo (execucao autonoma normal, sem reabertura), a secao 0.4 continua sendo avaliada normalmente, exatamente como hoje — nenhuma mudanca de comportamento no caminho sem --reopen.

Se NAO detectado: seguir 0.1-0.3 normalmente (fluxo interativo).

0.1 Classificar o pedido¶

Analise $ARGUMENTS e classifique em uma das categorias:

Feature nova: comportamento/capacidade que o sistema nao tem hoje, com multiplos atores, fluxos ou regras de negocio → SDD completo se paga.
Ajuste/extensao pontual: mudanca pequena em feature existente, uma regra nova, um campo a mais → SDD provavelmente e overkill.
Bugfix: correcao de comportamento incorreto → NAO usar specify, sugerir a skill bugfix.
Refactor/tarefa tecnica: mudanca interna sem impacto funcional observavel → NAO usar specify, sugerir execucao direta ou execute-task.

0.2 Avaliar relevancia do SDD¶

Considere sinais de que o SDD completo vale o custo: - Feature tem 2+ user stories independentes? - Envolve multiplos atores ou papeis? - Tem regras de negocio ou edge cases nao triviais? - Precisa alinhar stakeholders antes de implementar? - Vai gerar backlog de tarefas para mais de uma sessao de trabalho?

Se a maioria e "nao", provavelmente o pedido pode ser resolvido inline ou com um UC/ADR pontual, sem passar pelo pipeline SDD.

0.3 Apresentar a analise e deixar o usuario decidir¶

Antes de criar diretorio ou arquivos, apresentar ao usuario:

## Triagem do pedido

**Classificacao**: [Feature nova | Ajuste pontual | Bugfix | Refactor]

**Analise de relevancia SDD**:
- [Justificar por que vale ou nao vale gerar spec completa]
- [Citar sinais especificos do pedido]

**Opcoes**:

1. **Executar direto** — resolver o pedido sem gerar artefatos SDD
   (recomendado se: escopo pequeno, bugfix, refactor, ajuste inline)
2. **Criar feature SDD completa** — gerar spec + seguir pipeline
   (recomendado se: feature com stories multiplas, stakeholders, backlog)
3. **Alternativa sugerida**: [ex: criar UC classico, ADR, rodar bugfix]

Qual caminho prefere?

NUNCA prosseguir para ETAPA 1 sem confirmacao explicita do usuario — unica excecao: o atalho 0.0, onde a confirmacao e herdada da invocacao do orquestrador. Se o usuario escolher opcao 1 ou 3, encerrar a skill e executar o caminho escolhido (ou delegar para skill apropriada).

0.4 Atualizar spec existente vs abrir feature nova¶

Antes de criar qualquer artefato (mesmo apos o usuario confirmar "Feature nova" em 0.3), verifique se o pedido de fato pede uma feature nova ou se e um refinamento de uma spec ja existente do portfolio (docs/specs/*/spec.md, excluindo _archived/):

Mesma intencao / refinamento — o pedido mantem os mesmos atores/objetivo de uma spec existente e apenas adiciona detalhe, ajusta escopo ou corrige um requisito dela → recomende atualizar essa spec.md existente (ela pode entrar em clarify para incorporar o ajuste) em vez de abrir um diretorio novo.
Intencao mudou / escopo expandiu — o pedido introduz atores novos, uma capacidade nao relacionada ao objetivo original de nenhuma spec existente, ou expande o escopo alem do que qualquer spec ja ratificada cobre → prossiga com a feature nova normalmente.
Nenhuma spec existente se relaciona ao pedido (caso mais comum) → prossiga direto para a feature nova, sem overhead de comparacao spec-a-spec — este criterio so se aplica quando ha candidata plausivel.

Ao recomendar "atualizar spec existente", cite o criterio aplicado explicitamente na resposta ao usuario, por exemplo:

Este pedido parece um refinamento de `docs/specs/{existing}/spec.md`
(mesma intencao/objetivo, apenas detalha escopo) — recomendo atualizar
essa spec via /clarify em vez de abrir uma feature nova. Prefere seguir
assim ou ainda quer uma feature nova separada?

O mesmo criterio e aplicado pela skill clarify (ver plugins/cstk/skills/clarify/SKILL.md ETAPA 2) quando a ambiguidade levantada durante a clarificacao poderia, de fato, constituir uma feature nova.

0.5 Modo de incremento — reabertura da propria feature¶

Aplicavel somente quando 0.0 detectou contexto de reabertura (.previous_round preenchido) — no caminho sem --reopen esta secao nunca dispara e nenhuma outra ETAPA muda de comportamento (feature-reopen FR-014).

O alvo e sempre docs/specs/<short>/spec.md da PROPRIA feature sendo reaberta (<short> = campo .short_name do state-dir corrente) — nunca uma spec nova, nunca outra feature do portfolio.

Pular ETAPA 2 (Criar Diretorio) — o diretorio e a spec ja existem (restaurados pelo passo 7.d do fluxo --reopen quando estavam arquivados).
Ler o incremento: .execution.target_project_description da execucao corrente e o texto passado a --reopen "<descricao>" — trate como o $ARGUMENTS das ETAPAs 1/3 para este modo.
Numerar o(s) FR(s) novo(s): extraia o maior FR-NNN ja presente na secao ### Functional Requirements de spec.md (grep -oE '\*\*FR-[0-9]+\*\*', maior numero, +1 em diante) — NUNCA reusar um numero ja existente, mesmo que a fase/tarefa correspondente ja tenha sido concluida em round anterior.
Escrever o(s) FR(s) seguindo as mesmas regras de 3.2 (testavel, foco no QUE, defaults razoaveis, jamais dado factual sem fonte — Principio VI) e apende-los ao final de ### Functional Requirements — sem tocar em nenhum FR existente.
Resolver o capability-slug (mesmo criterio de checklists/requirements.md CHK005 de feature-reopen, reusar em vez de fragmentar): grep -l "Introduzida por: <short>" docs/specs/current/*.md 2>/dev/null. Achou exatamente um arquivo → reuse o slug (basename sem .md). Nao achou nenhum → use <short> como slug (ja e kebab-case valido). Achou mais de um → escolha o mais proximo semanticamente do incremento e registre a escolha (julgamento do autor, nao erro — a validacao de FORMA do slug fica a cargo de delta-gate.sh).
Apender ao ## Delta Requirements (criar a secao no fim do arquivo se ainda nao existir; se ja existir de um round anterior, apenas apender um novo bloco ### Capability: ao final — nunca reescrever ou remover blocos anteriores):

## Delta Requirements

### Capability: <slug>

#### ADDED

- **FR-NNN**: <mesmo texto do passo 4>

Os IDs FR-NNN DEVEM ser identicos aos gravados no passo 4 (regra 4 do contrato delta-section-format.md) — a secao Delta Requirements REPETE por contrato os mesmos IDs da secao Functional Requirements, nunca inventa IDs novos so para o bloco. 7. Nunca criar um segundo spec.md para a mesma feature — se por qualquer motivo docs/specs/<short>/spec.md nao existir neste ponto, e um bloqueio humano (a restauracao do passo 7.d deveria te-lo criado), nao uma oportunidade de gerar um arquivo novo. 8. Pular ETAPA 1-3 normais (ja cobertas pelos passos 2-6 acima) e ir direto para ETAPA 4 (Validacao) sobre o spec.md atualizado, depois ETAPA 6 (Salvamento/relatorio). ETAPA 5 (Clarificacao interativa) nao se aplica em modo autonomo (0.0 ja cobre isso).

Auto-checagem recomendada (best-effort, nunca bloqueia a pipeline — o gate validate-documentation ja roda depois de specify via Quality Gates do orquestrador):

~/.claude/skills/review-features/scripts/delta-gate.sh \
  "docs/specs/<short>/spec.md"

Deve sair 0 com RESULT|...|delta=present|errors=0|... (Scenario 10 de docs/specs/feature-reopen/quickstart.md).

ETAPA 1: ANALISE¶

1.1 Parsear Descricao¶

Extraia do input ($ARGUMENTS): - Atores: Quem usa a feature (usuarios, admins, sistemas) - Acoes: O que a feature permite fazer - Dados: Que entidades/informacoes estao envolvidas - Restricoes: Limites, regras, condicoes

1.2 Ler Contexto do Projeto¶

SEMPRE LER (se existirem):
-- README.md
-- CLAUDE.md
-- docs/constitution.md (para alinhar com principios)
-- docs/specs/ (para verificar IDs existentes e evitar duplicatas)

ETAPA 2: ESTRUTURA¶

2.1 Gerar Short Name¶

Crie um nome curto (2-4 palavras, kebab-case) que capture a essencia da feature: - Formato acao-substantivo quando possivel - Preservar termos tecnicos e siglas - Exemplos: - "Quero adicionar autenticacao de usuario" → user-auth - "Implementar integracao OAuth2 para a API" → oauth2-api-integration - "Criar dashboard de analytics" → analytics-dashboard

2.2 Criar Diretorio¶

Criar docs/specs/{short-name}/ (ou caminho sugerido pelo usuario).

ETAPA 3: ESPECIFICACAO¶

3.1 Template da Feature Spec¶

Ler o template em templates/feature-spec.md (mesmo diretorio desta skill) e preencher com conteudo concreto derivado da descricao. Estrutura:

User Scenarios & Testing — stories priorizadas (P1..Pn) + edge cases
Requirements — functional requirements e key entities
Success Criteria — measurable outcomes, technology-agnostic

Para ver exemplos de spec bem escrita vs mal escrita: - examples/spec-good.md — ilustra stories independentes, success criteria mensuraveis, zero detalhes de implementacao - examples/spec-bad.md — catalogo de anti-patterns (jargao tecnico em SC, stories acopladas, adjetivos vagos, excesso de [NEEDS CLARIFICATION])

3.2 Regras de Preenchimento¶

User Stories: - Priorizadas como jornadas de usuario ordenadas por importancia - Cada story deve ser INDEPENDENTEMENTE TESTAVEL - Se implementar apenas UMA story, ainda deve haver um MVP viavel - Adicionar quantas stories forem necessarias (P1, P2, P3, P4...)

Functional Requirements: - Cada requisito deve ser testavel - Foco no QUE o sistema faz, nao COMO implementar - Usar defaults razoaveis para detalhes nao especificados: - Retencao de dados: praticas padrao da industria - Performance: expectativas padrao para web/mobile - Tratamento de erros: mensagens user-friendly com fallbacks - Autenticacao: session-based ou OAuth2 para web apps - Para ambiguidades criticas, marcar com [NEEDS CLARIFICATION: pergunta especifica] - MAXIMO 3 marcadores [NEEDS CLARIFICATION] no total - Prioridade de clarificacao: escopo > seguranca > UX > detalhes tecnicos

INEGOCIAVEL — defaults NAO valem para dado factual (Constitution VI). A regra "usar defaults razoaveis" acima cobre POLITICAS de design nao especificadas (retencao, performance, tratamento de erro, auth). Ela NUNCA autoriza inventar dado factual de um sistema externo: nomes de propriedades de payload, assinaturas de request/response, URLs/endpoints/querystrings, valores concretos (financeiros, status, IDs, datas). Esses so entram na spec se vierem de fonte rastreavel (codigo, OpenAPI, doc, resposta real). Sem fonte → [NEEDS CLARIFICATION]; nunca um nome de campo ou endpoint suposto.

Decisoes de Infraestrutura Auditaveis (obrigatorio para features com runtime de longo prazo):

Features que envolvem schedulers, sessoes persistentes, refresh de tokens externos ou rotacao de chaves DEVEM declarar essas politicas como FRs explicitos no spec — NAO como divida descoberta na execucao. Razao: a execucao-fonte do agente-00c teve scheduling (sug-016), encryption key rotation (sug-011) e refresh policy (sug-015) descobertos na onda-007 como pendencias urgentes; deveriam ter sido FRs desde o spec.

Checklist minimo (cada item vira FR explicito quando aplicavel):

Tipo de decisao	FR explicito sugerido	Quando aplicar
Politica de scheduling	`FR-NN-INFRA-SCHED: autoSchedule = 'cron' \\| 'wakeup' \\| 'manual' \\| 'auto' (default <X>)`	Feature dispara trabalho periodico ou agendado
Politica de key rotation	`FR-NN-INFRA-KEY: SESSION_ENCRYPTION_KEY suporta versionamento (v1:<base64>, v2:<base64>) — rotacao sem downtime`	Feature criptografa dados persistentes
Refresh policy (token externo)	`FR-NN-INFRA-REFRESH: refresh on-demand + job periodico a cada Xmin; gap window aceitavel: Y min`	Feature consome IdP, OAuth, ou recurso com TTL
Mutex multi-pod	`FR-NN-INFRA-LOCK: serializacao cross-pod via <pg_try_advisory_xact_lock\\|redis lock\\|SELECT FOR UPDATE>`	Deploy multi-replica + estado compartilhado
Backup / restore	`FR-NN-INFRA-BACKUP: snapshot cron Xh, retencao Yd, restore tested via RB-NNN`	Feature persiste dados criticos
Idempotencia	`FR-NN-INFRA-IDEMP: <chave de idempotencia, TTL, scope>`	Feature aceita request retry

Se a feature NAO toca nenhum desses, anotar explicitamente uma linha > Decisoes de infraestrutura: N/A (feature stateless, sem scheduling). NAO deixar implicito — N/A explicito > silencio.

Success Criteria: - DEVEM ser mensuráveis (tempo, porcentagem, contagem, taxa) - DEVEM ser technology-agnostic (sem frameworks, linguagens, databases) - DEVEM ser user-focused (perspectiva do usuario/negocio) - DEVEM ser verificaveis sem conhecer detalhes de implementacao

Exemplos de Success Criteria BEM escritos: - "Usuarios completam checkout em menos de 3 minutos" - "Sistema suporta 10.000 usuarios concorrentes" - "95% das buscas retornam resultados em menos de 1 segundo"

Exemplos de Success Criteria MAL escritos (implementation-focused): - "API response time under 200ms" (muito tecnico) - "Database handles 1000 TPS" (detalhe de implementacao) - "React components render efficiently" (framework-specific)

Delta Requirements (opcional — secao ## Delta Requirements):

Preencher quando a feature adiciona, muda, remove ou renomeia comportamento HOJE ATIVO do sistema-alvo (algo ja documentado no corpus canonico docs/specs/current/) — contrato completo em docs/specs/living-specs/contracts/delta-section-format.md.

Antes de declarar uma ### Capability: <slug> NOVA, rodar ls docs/specs/current/*.md 2>/dev/null (lista vazia e resultado valido — corpus pode nao existir ainda) e reusar o slug ja existente sempre que a feature tocar o MESMO conceito, em vez de fragmentar em um slug novo semanticamente equivalente (ex.: commit-mode vs commit-staging referindo-se ao mesmo mecanismo). Essa decisao e julgamento do autor da spec — a validacao de FORMA do slug fica a cargo de delta-gate.sh, rodado apenas no momento do archive (specify nunca invoca o gate diretamente).
Feature que nao toca comportamento ativo (puramente nova, ou doc-only/meta) usa o marcador de Skip em vez dos blocos ### Capability: (mutuamente exclusivos): **Skip**: <justificativa nao-vazia> — <autor>, <YYYY-MM-DD> — os 3 campos sao obrigatorios.
Exemplo minimo de bloco preenchido:

## Delta Requirements

### Capability: commit-mode

#### ADDED

- **FR-018**: Sistema MUST suportar staging por allowlist derivada no
  modo atomic-commit

ETAPA 4: VALIDACAO¶

4.1 Checklist de Qualidade Interna¶

Valide a spec contra estes criterios:

4.2 Auto-Correcao¶

Se itens falham na validacao: 1. Listar itens que falharam e problemas especificos 2. Atualizar a spec para corrigir cada problema 3. Re-validar (max 3 iteracoes) 4. Se ainda falhando apos 3 iteracoes: documentar problemas restantes e avisar usuario

4.3 Gate de cobertura de cenarios (requirement-coverage.sh)¶

Antes de reportar conclusao bem-sucedida (ETAPA 6.2), garanta que o spec.md corrente esteja persistido em docs/specs/{short-name}/spec.md (escreva/ atualize o arquivo agora se a 6.1 formal ainda nao rodou) e rode o gate deterministico:

plugins/cstk/skills/checklist/scripts/requirement-coverage.sh docs/specs/{short-name}/spec.md

Exit 0 (zero FINDING): seguir normalmente para ETAPA 5/6.
Exit 1 (>=1 FINDING|error|fr-no-scenario|...): a falha impede o relatorio de sucesso da ETAPA 6.2. Reportar cada FINDING ao usuario (ID exato + sugestao de correcao) e voltar para 3.2/4.2: adicionar um Acceptance Scenario ou Edge Case cobrindo os termos centrais do requisito apontado, depois re-rodar o gate (mesmo limite de 3 iteracoes da 4.2).
Exit 2 (uso incorreto/arquivo ausente): reportar o erro ao usuario; nao bloqueia por si so (indica problema no proprio script ou no path, nao na spec).
Em execucao autonoma (agente-00c/feature-00c), registrar a invocacao via state-ondas.sh record-skill --skill requirement-coverage --kind gate (script deterministico, nao tool Skill).

ETAPA 5: CLARIFICACAO¶

5.1 Resolver [NEEDS CLARIFICATION]¶

Se existem marcadores [NEEDS CLARIFICATION] na spec:

Extrair todos os marcadores
Se mais de 3: manter apenas os 3 mais criticos e fazer guesses informados para o resto
Para cada marcador, apresentar ao usuario:

## Questao [N]: [Topico]

**Contexto**: [Citar secao relevante da spec]

**O que precisamos saber**: [Pergunta especifica]

**Respostas Sugeridas**:

| Opcao | Resposta | Implicacoes |
|-------|----------|-------------|
| A     | [Primeira opcao] | [O que significa para a feature] |
| B     | [Segunda opcao] | [O que significa para a feature] |
| C     | [Terceira opcao] | [O que significa para a feature] |

**Sua escolha**: _[Aguardar resposta]_

Apos respostas: atualizar spec substituindo marcadores pelas respostas

ETAPA 6: SALVAMENTO¶

6.1 Salvar Spec¶

Salvar em docs/specs/{short-name}/spec.md.

6.2 Reportar¶

## Spec Criada

**Feature**: {short-name}
**Arquivo**: docs/specs/{short-name}/spec.md
**Status**: Draft
**User Stories**: {N} stories (P1-P{N})
**Requisitos**: {N} functional requirements
**Clarificacoes pendentes**: {N}

### Proximos Passos

1. `/clarify` — Refinar ambiguidades na spec (se houver NEEDS CLARIFICATION)
2. `/plan` — Gerar plano tecnico de implementacao

DIRETRIZES RAPIDAS¶

Foco no QUE usuarios precisam e POR QUE
Evitar COMO implementar (sem tech stack, APIs, estrutura de codigo)
Escrito para stakeholders de negocio, nao desenvolvedores
Quando secao nao se aplica: remover inteiramente (nao deixar como "N/A")
Pensar como tester: todo requisito vago deve falhar no checklist de qualidade

Gotchas¶

ZERO detalhes de implementacao na spec¶

Sem linguagens, frameworks, APIs, estrutura de codigo, nomes de bibliotecas, classes. A spec responde QUE e POR QUE — o COMO vai para /plan. Se aparece "em React" ou "com PostgreSQL" na spec, esta errado.

Success Criteria devem ser technology-agnostic E mensuraveis¶

Correto: "Usuario completa checkout em <3 minutos", "95% das buscas retornam <1s", "Sistema suporta 10k usuarios concorrentes". Errado: "API responde <200ms" (tecnico), "Database aguenta 1000 TPS" (implementacao), "Componentes React renderizam rapido" (framework).

Maximo 3 `[NEEDS CLARIFICATION]` — priorizar escopo > seguranca > UX > tech¶

Mais de 3 marcadores indica que a spec deveria voltar ao usuario antes de escrever. Priorize o que impacta corretude e use defaults informados para o resto.

Cada user story deve ser INDEPENDENTEMENTE TESTAVEL¶

Se implementar apenas P1 nao ha MVP viavel, as stories estao acopladas demais. Cada story precisa ter valor isolado para o usuario.

Nao deixar secoes vazias com "N/A"¶

Se a feature nao envolve entidades de dados, remover a secao "Key Entities" inteira — nao deixar header com "N/A" abaixo. Secoes vazias sao ruido para o /plan e /create-tasks downstream.

Defaults razoaveis ao inves de [NEEDS CLARIFICATION] para tudo¶

Retencao de dados, tratamento de erros padrao, autenticacao web-padrao — se nao critico, use o default da industria e documente a suposicao. Marcar tudo como pendente trava o fluxo.