Imported from promovaweb/specsfy (
skills/specsfy-update-spec/SKILL.md). Install upstream withnpx skills add promovaweb/specsfy --skill specsfy-update-spec. Copyright stays with the author.
Atualizar uma especificação existente
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. O objetivo é reabrir apenas o que a mudança realmente invalida, para preservar o trabalho ainda válido.
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. Perguntas sobre
decisões materiais pertencem ao refinamento em $specsfy-02-backlog.
Pronto quando
- o pedido está preservado literalmente e classificado;
- a
spec.mdreflete a mudança com IDs preservados, e a razão está registrada na seção adequada; - somente os gates afetados voltaram para
Pending, especsfy gate spec <spec> --allow-draftpassa; - a próxima skill do fluxo foi carregada, ou as lacunas foram relatadas quando
o refinamento terminou por
avançar.
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-update-spec → $<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-update-spec — 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.
Confirmar a entrada
- Preserve literalmente o novo pedido antes de interpretá-lo.
- Leia em paralelo a spec canônica em
specs/<estado>/<NNNN>-<slug>/spec.md(metadados, requisitos, cenários, plano, tarefas, gates e evidências), as instruções do projeto,PROJECT.md,.specsfy/STACK.md,.specsfy/RULES.md,.specsfy/DATABASE.mde o research indexado aplicável. - Inspecione mudanças Git preexistentes na spec para não atribuí-las ao pedido atual.
- Se não existir uma spec, anuncie a pendência e carregue
$specsfy-02-backlogpara uma ideia superficial ou$specsfy-03-specifyquando já houver intenção explícita de criar a fatia. - Se a spec ainda estiver em
Drafte nunca tiver obtidoDefinition 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 quando o pedido puder alterar comportamento, plano ou fronteira entre specs.
| Tipo de pedido | O que fazer |
|---|---|
| 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-06-implement no modo implement |
| esclarecimento editorial sem mudança de significado | preserve os gates e altere somente a redação necessária |
| mudança de comportamento, aceite, escopo, dados, segurança ou interface | reabra desde o Ato I |
| mudança somente de solução, tarefas ou estratégia de testes | reabra desde o Ato II |
| capacidade independente da finalidade e dos atores da fatia atual | não acrescente em silêncio; 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
Corrigir checklists residuais
Quando o progresso apontar itens do ciclo sem tarefa, confira as linhas na spec e localize a tarefa correspondente.
- Se o texto apenas repetir uma tarefa concluída, ofereça convertê-lo em anotação sem checkbox, preservando o texto e citando o ID da tarefa que o substituiu. Preserve status e gates somente se nenhum trabalho ou significado mudar. Não apague o registro automaticamente.
- Se o trecho representar trabalho necessário, reconcilie o plano pelo Ato II. Ao promover um rascunho para tarefa, converta o bloco de origem em anotação com a referência à tarefa criada.
Execute o progresso novamente para conferir as contagens e as linhas remanescentes.
Atualizar a fonte canônica
-
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, então não repita a confirmação.
-
Edite somente
spec.mde o research indexado necessário, sem criarchange-request.md,plan.md,tasks.md,research.mdou outra fonte paralela. -
Atualize todas as seções normativas afetadas e preserve IDs e decisões ainda válidos, sem renumerar 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.
-
Atualize as referências a especialistas quando a mudança trouxer novos sinais, conforme a seção Especialistas.
-
Mantenha a evidência histórica como foi produzida e marque como pendente toda prova posterior que dependa da versão invalidada.
-
Execute a projeção de impacto:
specsfy specs change <spec> --base HEAD --mode impactPelo MCP, use a tool
spec_change_analyze. Sem o binário instalado, rode o script equivalente:node .agents/skills/specsfy-update-spec/scripts/analyze_change.mjs \ specs/<estado>/<NNNN>-<slug>/spec.md --base HEAD --mode impactUse
--mode changelogpara listar IDs adicionados, removidos e alterados. A classificação usa títulos canônicos, não números de seção, eunknownreabre do Ato I por segurança. O comando é somente leitura e não substitui a comparação semântica com o pedido.
Especialistas
Quando a mudança trouxer um sinal novo, use
a tabela de sinais para atualizar a linha
Especialistas do cabeçalho e a subseção #### Especialistas da seção 8.
Registre o modo, o sinal e as fases. Carregue a skill quando a revisão
depender dela, seguindo o protocolo da referência.
Invalidar somente o necessário
| Alcance | Status e gates |
|---|---|
| Ato I | Status: Draft, Definition Gate: Pending, Plan Gate: Pending e Delivery Gate: Pending |
| somente Ato II | Status: Defined, preserve Definition Gate: Passed e retorne Plan Gate e Delivery Gate para Pending |
| esclarecimento editorial comprovadamente sem mudança semântica | preserve status e gates |
Um gate posterior não permanece aprovado sobre uma entrada invalidada.
Preserve tarefas e evidências ainda válidas; $specsfy-05-tasks reconcilia os
itens afetados e suas dependências antes de novo RED.
Valide a estrutura intermediária:
specsfy gate spec <spec> --allow-draft
Pelo MCP, use a tool gate_spec. Sem o binário instalado, rode o script
equivalente:
node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs \
specs/<estado>/<NNNN>-<slug>/spec.md --allow-draft
Retomar o fluxo
- Mudança desde o Ato I: carregue
$specsfy-04-validatee depois percorra tarefas, o modotestsde$specsfy-06-implemente a etapa que originou a mudança. Se o refinamento do backlog terminou poravanç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-implementno modotestse retoma a origem. - Mudança detectada durante a implementação: retome
$specsfy-06-implementno modoimplementsomente depois de Definition e Plan Gate voltarem aPassede existir RED válido para o comportamento novo ou alterado. - Mudança detectada depois de
Complete: percorra novamente os atos invalidados e só restaureCompletecom Delivery Gate e DoD comprovados.
Relatar
Comece dizendo que o pedido foi incorporado e que o fluxo necessário será retomado automaticamente; a complexidade do framework vem depois do resultado. Em seguida, informe o pedido preservado, a spec alterada, a classificação, os IDs e as seções afetados, os gates invalidados, as evidências preservadas ou tornadas pendentes e a próxima skill carregada.
