# Specsfy 03 Specify > 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/draft/` 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. - Skill: `promovaweb/specsfy-03-specify` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add promovaweb/specsfy-03-specify` - Raw SKILL.md: https://api.skillmd.com/api/skills/promovaweb/specsfy-03-specify/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: promovaweb (https://skillmd.com/u/promovaweb) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/promovaweb/specsfy-03-specify --- # Montar a especificação única ## Preparação obrigatória Antes de executar esta skill, carregue obrigatoriamente `$specsfy-setup` na raiz do projeto. Em handoff automático, carregue-o de novo antes desta etapa. Reutilize a raiz confirmada na conversa e não prossiga se o setup apontar uma pendência. ## Modo de interação Modo de interação: `perguntas`. Antes de formular qualquer pergunta, leia e aplique o `Contrato de perguntas numeradas` de `.specsfy/Spec.md`. Crie ou atualize o pacote `specs/draft/-/`, 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. Antes de consolidar uma spec Laravel, leia `.specsfy/PACKAGES.md`, `docs/packages/README.md` e as fichas de `docs/packages/`. Se a solicitação trouxer uma URL GitHub de pacote ou depender de uma biblioteca Composer, carregue `$specsfy-specialist-laravel-package-manager` para conferir se o pacote já existe e registrar a necessidade sem duplicar dependências. ## Orquestrar a conversa Ao concluir esta etapa ou detectar trabalho de outra etapa, anuncie `Pendência detectada: — 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 → $ — motivo: — resultado esperado: ` 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: $ → $specsfy-03-specify — pendência resolvida: ` 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 node /scripts/iniciar_spec.mjs \ --title "" [--slug ] [--root ] ``` 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/draft/-/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. 8. Leia `.specsfy/DATABASE.md` quando existir. Se a jornada depender de informações guardadas e o arquivo não explicar o que o produto precisa lembrar, quem usa essas informações ou quando elas deixam de ser necessárias, carregue `$specsfy-data-discovery` e retome esta skill depois do registro confirmado. ## 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 limitado a oito perguntas por área 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. 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 `/specs/draft/-/spec.md`; o ID pertence ao diretório e o arquivo permanece exatamente `spec.md`. - Use `/specs/draft/-/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/-.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/-.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 `-` 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. - Quando o cabeçalho declarar `Interface para pessoas: Sim`, preencha na seção 10 as nove partes do template com stack e convenções locais, telas, fluxo de informação, menus e navegação principal, formulários e ações, composição, blocos React e componentes shadcn/ui/ReUI, estados e acessibilidade. Use `INTERFACE.md`, `.specsfy/STACK.md`, manifests, telas e código existente como fonte da stack e do sistema atual; registre o que será preservado e alterado. Não proponha biblioteca incompatível nem reestruture uma tela existente sem esse exame. Carregue `$specsfy-specialist-ux-design`, `$specsfy-specialist-ui-design` e o especialista da stack de interface. Não aceite uma descrição de CRUD que tenha somente API, banco ou serviço. Em Laravel com React, registre explicitamente shadcn/ui e ReUI, todos os blocos React previstos, suas responsabilidades, arquivos, componentes de origem e regra de reuso. A página apenas compõe esses blocos. - Quando não houver interface, declare `Interface para pessoas: Não` e explique por que a entrega não será usada por uma pessoa em uma tela. - 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 node .agents/skills/specsfy-03-specify/scripts/load_research.mjs \ specs//-/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//-/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//-/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.