--- name: specsfy-03-specify description: "Use quando o usuário pede para promover uma entrada ou backlog já refinado, criar, iniciar ou consolidar uma especificação nova ou ainda em Draft em `spec.md`. Use também quando uma transição automática exigir criar ou completar a fonte normativa inicial. Inicializa specs em `specs/specs/` e aplica o MCR-10; para mudar spec aprovada use specsfy-update-spec, para captura sem perguntas use specsfy-01-inbox, para refinamento use specsfy-02-backlog e para revisão sem edição use specsfy-04-validate." ---

# Montar a especificação única

Crie ou atualize o pacote `specs/specs/<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

1. 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. 2. Ao criar uma spec, resolva o diretório desta skill e execute antes de escrever:

```bash python3 -B <diretório-da-skill>/scripts/iniciar_spec.py \ --title "<nome da especificação>" [--slug <slug>] [--root <raiz>] ```

3. 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/specs/<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`. 4. Ao atualizar, use o caminho da spec existente fornecido ou descoberto sob a raiz atual; não execute o inicializador novamente. 5. 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. 6. 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. 7. Leia `references/mcr-10.md` ao receber relato, história, transcrição ou especificação a refinar.

## Aplicar o MCR-10

1. Preserve a formulação original e identifique finalidade, ator e resultado. 2. Analise termos ambíguos, equivalências terminológicas e derivações. 3. 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. 4. Distinga cada declaração da pessoa de inferência, hipótese, decisão, conflito ou questão aberta produzida durante a análise. 5. 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`, registre as lacunas na fonte normativa, mantenha `Status: Draft` e `Definition Gate: Pending`; não promova a spec a `Defined` e não reabra o mesmo ciclo nesta retomada. 6. Recombine decisões em afirmações com sujeito, condição, ação e efeito observável; derive regras, histórias, Gherkin, limites e falhas. 7. 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/specs/<NNNN>-<slug>/spec.md`; o ID pertence ao diretório e o arquivo permanece exatamente `spec.md`. - Use `<raiz>/specs/specs/<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` e `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 python3 -B .agents/skills/specsfy-03-specify/scripts/load_research.py \ specs/specs/<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 python3 .agents/skills/specsfy-04-validate/scripts/validate_spec.py specs/specs/<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` e `Status: Defined`. Até lá, mantenha `Status: Draft`, `Definition Gate: Pending` e relate decisões bloqueantes.

## Relatar

Informe:

- caminho `specs/specs/<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](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.