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: <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

1. Preserve literalmente o novo pedido antes de interpretá-lo.
2. Localize a spec canônica em

specs/<estado>/<NNNN>-<slug>/spec.md e leia seus metadados, requisitos, cenários, plano, tarefas, gates e evidências.

1. Leia as instruções do projeto, PROJECT.md, .specsfy/STACK.md,

.specsfy/RULES.md, .specsfy/DATABASE.md e o research indexado aplicável.

1. Inspecione mudanças Git preexistentes na spec e não as atribua ao pedido

atual.

1. 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.

1. 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 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.

1. 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.

1. 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.

1. 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.

1. Execute a projeção de impacto:

node .agents/skills/specsfy-update-spec/scripts/analyze_change.mjs \
  specs/<estado>/<NNNN>-<slug>/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:

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-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.