Montar a especificação única

Modo de interação

Modo de interação:

perguntas

. Antes de formular qualquer pergunta, leia e aplique o

Contrato de perguntas numeradas

.specsfy/Spec.md

Crie ou atualize o pacote

specs/draft/<NNNN>-<slug>/

, no qual

spec.md

é a única fonte normativa de todo o fluxo SDD. Somente o diretório recebe o número; mantenha o arquivo sempre como

spec.md

. Consolide descoberta, research, esclarecimentos, produto, plano técnico, modelo de dados, contratos, TDD, BDD, validações, tarefas, decisões e conclusão em três atos explícitos. Evidências externas consultadas vivem em

research/

; não gere

plan.md

research.md

data-model.md

tasks.md

, checklists ou uma segunda especificação.

Orquestrar a conversa

Ao concluir esta etapa ou detectar trabalho de outra etapa, anuncie

Pendência detectada: <descrição> — ação: resolvendo nesta etapa

e resolva-a quando pertencer ao próprio escopo. Quando houver troca de responsabilidade, anuncie

Transição automática: $specsfy-03-specify → $<destino> — motivo: <motivo> — resultado esperado: <resultado>

e carregue imediatamente a skill de destino, sem pedir confirmação nem repetir o comando. Continue na mesma conversa. Depois de uma correção necessária a esta etapa, anuncie

Retomada automática: $<destino> → $specsfy-03-specify — pendência resolvida: <resultado>

e retome-a imediatamente. Reavalie o estado após cada handoff para evitar ciclos. Não peça confirmação para o handoff; ações sensíveis continuam exigindo autorização específica.

Preparar

Resolva a raiz do projeto pelo diretório informado pelo usuário ou por
```
Path.cwd()
```
quando ele não informar outro. Não procure nem promova o destino para uma raiz Git.
Ao criar uma spec, resolva o diretório desta skill e execute antes de escrever:

bash

node <diretório-da-skill>/scripts/iniciar_spec.mjs \
  --title "<nome da especificação>" [--slug <slug>] [--root <raiz>]

Use o caminho absoluto impresso pelo script. Ele aloca o próximo ID local, prefere
```
.specsfy/templates/custom/Spec.md
```
, recorre ao template gerenciado
```
.specsfy/templates/Spec.md
```
e cria somente
```
specs/draft/<NNNN>-<slug>/spec.md
```
; nunca renomeie o arquivo para incluir o ID. Ao desenvolver este repositório, o script usa
```
skills/templates/Spec.md
```
como fallback; no projeto consumidor, template ausente exige
```
specsfy install
```
.
Ao atualizar, use o caminho da spec existente fornecido ou descoberto sob a raiz atual; não execute o inicializador novamente.
Leia a captura de origem em
```
specs/inbox/
```
, o item de backlog, o brief da refinamento do backlog, o pedido atual, a spec nesse caminho, seu
```
research/
```
e arquivos do repositório que revelem restrições reais.
Se não houver informação suficiente para identificar problema, ator e resultado, anuncie a pendência e carregue
```
$specsfy-02-backlog
```
para executar o ciclo. Retome esta skill ao final do ciclo e use o brief completo ou parcial produzido.
Leia
```
references/mcr-10.md
```
ao receber relato, história, transcrição ou especificação a refinar.

Aplicar o MCR-10

Preserve a formulação original e identifique finalidade, ator e resultado.
Analise termos ambíguos, equivalências terminológicas e derivações.
Use substância, quantidade, qualidade, relação, lugar, tempo, posição, posse, ação e afecção como lentes adaptativas, não como questionário.
Distinga cada declaração da pessoa de inferência, hipótese, decisão, conflito ou questão aberta produzida durante a análise.
Se existir lacuna aplicável, carregue
```
$specsfy-02-backlog
```
para executar o ciclo sem limite e retome esta skill ao final do ciclo. Se a pessoa escolher
```
avançar
```
, aplique a confirmação e o registro definidos no contrato central. Mantenha
```
Status: Draft
```
e
```
Definition Gate: Pending
```
quando restarem pontos aplicáveis; não promova a spec a
```
Defined
```
e não reabra o mesmo ciclo nesta retomada.
Recombine decisões em afirmações com sujeito, condição, ação e efeito observável; derive regras, histórias, Gherkin, limites e falhas.
Registre o resultado nas seções existentes de
```
spec.md
```
; não gere relatório MCR separado nem copie a referência para o pacote da fatia.

Escrever

Grave sempre em
```
<raiz>/specs/draft/<NNNN>-<slug>/spec.md
```
; o ID pertence ao diretório e o arquivo permanece exatamente
```
spec.md
```
.
Use
```
<raiz>/specs/draft/<NNNN>-<slug>/research/
```
somente para cópias, snapshots, contratos, schemas, exemplos e notas de proveniência realmente consultados. Não coloque código de produção, testes ou documentos normativos nesse diretório.
Ao pesquisar uma API ou documentação externa, armazene a evidência permitida em
```
research/
```
e indexe caminho, origem, versão/data, licença e impacto em
```
Artefatos de pesquisa armazenados
```
. Se licença ou termos impedirem a cópia, armazene metadados, URL, data de acesso, checksum/versão quando disponível e notas próprias, sem reproduzir conteúdo protegido.
Fora de
```
spec.md
```
e
```
research/
```
, não crie outra entrada no pacote da feature.
Ao promover
```
specs/backlog/<NNNN>-<slug>.md
```
, registre esse caminho na spec e atualize o item para
```
Status: Promoted
```
com o caminho da spec criada. O backlog preserva proveniência, mas deixa de governar o comportamento.
Ao derivar diretamente de
```
specs/inbox/<data-hora>-<slug>.md
```
, registre o caminho na spec e preserve a captura sem alteração. A análise inicial é contexto, não requisito confirmado.
Preserve o cabeçalho como uma tabela Markdown de duas colunas,
```
Campo
```
e
```
Valor
```
; não converta seus metadados em linhas
```
**Campo**: valor
```
.
Na tabela, declare
```
ID
```
como
```
SPEC-NNNN
```
e
```
Slug
```
como
```
<NNNN>-<slug>
```
e mantenha o slug igual ao diretório pai.
Preserve exatamente os três atos e as 18 seções do template resolvido:
```
.specsfy/templates/custom/Spec.md
```
quando existir ou
```
.specsfy/templates/Spec.md
```
caso contrário.
Substitua o conteúdo editorial restante do modelo durante o refinamento; não deixe seus exemplos ou placeholders na spec promovida para
```
Defined
```
.
Ao atualizar, edite o arquivo existente e preserve IDs e decisões ainda válidas.
Numere novos itens sem reutilizar ou renumerar IDs removidos:
- histórias:
```
US-001
```
  ;
- requisitos funcionais:
```
FR-001
```
  ;
- requisitos não funcionais:
```
NFR-001
```
  ;
- cenários de aceite:
```
AC-001
```
  ;
- decisões:
```
DEC-001
```
  .
Escreva cada requisito como comportamento verificável.
Escreva cada cenário com Given/When/Then e associe-o a pelo menos um requisito.
Defina no mínimo três
```
AC
```
distintos para a feature inteira e para cada
```
US
```
,
```
FR
```
e
```
NFR
```
. Conte cobertura somente quando o
```
AC
```
declarar o ID em
```
**Cobre**
```
; use caminho feliz, variação/regra crítica e falha ou limite material para ampliar contexto sem duplicar cenários equivalentes.
Inclua fora de escopo, erros, limites, segurança e acessibilidade quando relevantes.
Mantenha a seção técnica concreta o bastante para permitir tarefas com caminhos de arquivo, sem confundir escolha interna com resultado do usuário.
Registre defaults reversíveis em
```
Suposições
```
; peça esclarecimento apenas quando opções plausíveis mudarem materialmente escopo, dados, segurança, UX ou testes.
Não deixe placeholders, exemplos do template,
```
TBD
```
,
```
TODO
```
ou marcadores de clarificação em um arquivo marcado como
```
Defined
```
.
Mantenha tarefas futuras na seção
```
14. Tarefas
```
; skills posteriores atualizam a mesma seção, nunca outro arquivo.
Use os metadados
```
Definition Gate
```
,
```
Plan Gate
```
e
```
Delivery Gate
```
para expressar prontidão sem criar relatórios separados.

Respeitar specs já aprovadas

Se a spec já obteve

Definition Gate: Passed

e a pessoa pedir para adicionar, remover, corrigir ou mudar algo, anuncie a pendência e carregue automaticamente

$specsfy-update-spec

. Essa skill classifica o impacto, atualiza a fonte normativa e invalida somente os gates afetados. Retome esta skill apenas se a mudança retornar a spec ao estado de definição inicial.

Preservar rastreabilidade

Para cada

FR

NFR

, aponte no mínimo três cenários

AC

e mantenha o método de verificação explícito dos NFRs. Para cada história, identifique os requisitos que entregam seu valor e ao menos três

AC

. Use os mesmos IDs mais tarde nos casos TDD e na seção 14.

Controlar research

Antes do planejamento, carregue somente as evidências indexadas e valide claims com:

bash

node .agents/skills/specsfy-03-specify/scripts/load_research.mjs \
  specs/<estado>/<NNNN>-<slug>/spec.md

Para pesquisa material, registre
```
R-ID
```
, criticalidade, claim, veredito, confiança, evidência local e orçamento na seção 2. Claim
```
critical
```
ainda não verificado bloqueia o handoff; claim refutado permanece registrado. IDs devem ser únicos, gasto não pode superar o limite e a âncora Markdown citada precisa existir no arquivo local.

Autovalidar

Enquanto o arquivo estiver em Draft, execute a validação estrutural intermediária:

bash

node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs specs/<estado>/<NNNN>-<slug>/spec.md --allow-draft

Corrija falhas estruturais em no máximo três ciclos. A skill

specsfy-04-validate

faz a revisão semântica, registra o resultado na seção 13 e promove

Definition Gate: Passed

Status: Defined

. Até lá, mantenha

Status: Draft

Definition Gate: Pending

e relate decisões bloqueantes.

Relatar

Informe:

caminho
```
specs/<estado>/<NNNN>-<slug>/spec.md
```
;
caminhos de research armazenados ou a declaração de que não houve fonte externa;
status;
contagem de
```
US
```
,
```
FR
```
,
```
NFR
```
e
```
AC
```
;
suposições relevantes;
transição automática para
```
$specsfy-04-validate
```
, com motivo e resultado esperado.

Especialistas sob demanda

Leia references/specialists.md quando requisitos, NFRs, dados ou decisões técnicas exigirem conhecimento especializado. Registre o requisito na spec e proponha carregar o especialista. Se ele não estiver instalado, peça autorização específica antes de instalar.

specsfy-03-specify

NPX Install

Tags

SKILL.md Content

Montar a especificação única

Modo de interação

Orquestrar a conversa

Preparar

Aplicar o MCR-10

Escrever

Respeitar specs já aprovadas

Preservar rastreabilidade

Controlar research

Autovalidar

Relatar

Especialistas sob demanda