# Specsfy Update Spec > Use quando o usuário esqueceu algo, quer adicionar, remover, corrigir ou mudar um pedido em uma spec existente que já foi definida, planejada, está sendo implementada ou foi concluída. Use também quando uma transição automática detectar mudança tardia de comportamento, escopo, aceite, dados, segurança ou plano. Atualiza a fonte normativa, invalida somente os gates afetados e coordena a retomada; para criar a spec inicial use specsfy-03-specify, para decidir uma ambiguidade use specsfy-02-backlog e para implementar use specsfy-07-implement. - Skill: `promovaweb/specsfy-update-spec` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add promovaweb/specsfy-update-spec` - Raw SKILL.md: https://api.skillmd.com/api/skills/promovaweb/specsfy-update-spec/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-update-spec --- # Atualizar uma especificação existente ## 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`. Incorpore um pedido surgido depois da definição inicial sem esconder a mudança, duplicar a fonte normativa ou obrigar a pessoa a conhecer atos e gates. ## 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-update-spec → $ — 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-update-spec — 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. ## Confirmar a entrada 1. Preserve literalmente o novo pedido antes de interpretá-lo. 2. Localize a spec canônica em `specs//-/spec.md` e leia seus metadados, requisitos, cenários, plano, tarefas, gates e evidências. 3. Leia as instruções do projeto, `PROJECT.md`, `.specsfy/STACK.md`, `.specsfy/RULES.md`, `.specsfy/DATABASE.md` e o research indexado aplicável. 4. Inspecione mudanças Git preexistentes na spec e não as atribua ao pedido atual. 5. Se não existir uma spec, anuncie a pendência e carregue `$specsfy-02-backlog` para uma ideia superficial ou `$specsfy-03-specify` quando já houver intenção explícita de criar a fatia. 6. Se a spec ainda estiver em `Draft` e nunca tiver obtido `Definition Gate: Passed`, carregue `$specsfy-03-specify`; esta skill governa somente a revisão de uma definição que já avançou. ## Classificar antes de escrever Leia [a matriz de classificação](references/change-classification.md) quando o pedido puder alterar comportamento, plano ou fronteira entre specs. - Para correção interna reversível sem efeito observável, não altere a spec: registre a avaliação na evidência da tarefa e retome `$specsfy-07-implement`. - Para esclarecimento editorial que não muda significado, preserve os gates e altere somente a redação necessária. - Para mudança de comportamento, aceite, escopo, dados, segurança ou interface, reabra desde o Ato I. - Para mudança somente de solução, tarefas ou estratégia de testes, reabra desde o Ato II. - Para capacidade independente da finalidade e dos atores da fatia atual, não a acrescente silenciosamente: carregue `$specsfy-02-backlog` ou `$specsfy-03-specify` conforme a maturidade do pedido. - Quando opções plausíveis mudarem materialmente o resultado, faça handoff para `$specsfy-02-backlog`, execute o ciclo adaptativo 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, reabra o Ato I quando restarem pontos aplicáveis, não encaminhe a definição como aprovada e não reabra o mesmo ciclo nesta retomada. Esta skill não cria uma spec nova, não decide requisito material pela pessoa, não altera código de produção e não implementa o pedido. ## Incorporar a mudança 1. Confirme que a pessoa autorizou incorporar o pedido à spec atual. O pedido explícito para mudar, adicionar, remover ou corrigir já constitui essa autorização; não repita a confirmação. 2. Edite somente `spec.md` e o research indexado necessário. Não crie `change-request.md`, `plan.md`, `tasks.md`, `research.md` ou outra fonte paralela. 3. Atualize todas as seções normativas afetadas, preserve IDs e decisões ainda válidos e nunca renumere IDs existentes. Para mudança de comportamento, registre razão, decisão e IDs impactados na seção 17. Para mudança somente de plano, registre a razão na seção de plano ou risco afetada sem criar uma decisão de produto artificial. 4. Não reescreva evidência histórica como se tivesse sido produzida para a nova entrada. Marque como pendente toda prova posterior que dependa da versão invalidada. 5. Execute a projeção de impacto: ```bash node .agents/skills/specsfy-update-spec/scripts/analyze_change.mjs \ specs//-/spec.md --base HEAD --mode impact ``` Use `--mode changelog` para listar IDs adicionados, removidos e alterados. A classificação usa títulos canônicos, não números de seção; `unknown` reabre do Ato I por segurança. O script é somente leitura e não substitui a comparação semântica com o pedido. ## Invalidar somente o necessário - Para mudança do Ato I, defina `Status: Draft`, `Definition Gate: Pending`, `Plan Gate: Pending` e `Delivery Gate: Pending`. - Para mudança somente do Ato II, defina `Status: Defined`, preserve `Definition Gate: Passed` e retorne `Plan Gate` e `Delivery Gate` para `Pending`. - Para esclarecimento editorial comprovadamente sem mudança semântica, preserve status e gates. - Nunca mantenha um gate posterior aprovado sobre uma entrada invalidada. - Preserve tarefas e evidências ainda válidas; `$specsfy-05-tasks` reconcilia itens afetados e suas dependências antes de novo RED. Valide a estrutura intermediária: ```bash node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs \ specs//-/spec.md --allow-draft ``` ## Retomar o fluxo - Mudança desde o Ato I: carregue `$specsfy-04-validate`; depois percorra tasks, TDD/BDD e a etapa que originou a mudança. Se o refinamento do backlog terminou por `avançar`, não faça esse handoff na mesma retomada: relate as lacunas e encerre com os gates pendentes. - Mudança somente do Ato II: carregue `$specsfy-05-tasks`, que reconcilia o plano, chama `$specsfy-06-tdd-bdd` e retoma a origem. - Mudança detectada durante implementação: retome `$specsfy-07-implement` somente depois de Definition e Plan Gate voltarem a `Passed` e existir RED válido para o comportamento novo ou alterado. - Mudança detectada depois de `Complete`: percorra novamente os atos invalidados e só restaure `Complete` com Delivery Gate e DoD comprovados. ## Relatar Informe o pedido preservado, a spec alterada, a classificação, os IDs e seções afetados, os gates invalidados, as evidências preservadas ou tornadas pendentes e a próxima skill carregada. Não exponha complexidade do framework antes do resultado: diga primeiro que o pedido foi incorporado e que o fluxo necessário será retomado automaticamente.