sda-adr-deprecate
Depreca uma ADR sem substituta e atualiza o índice. Use quando a decisão deixou de se aplicar.
- License 许可
- Apache-2.0
- 最近更新
- 2026-07-31
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sda-adr-deprecate
- description
- Depreca uma ADR sem substituta e atualiza o índice. Use quando a decisão deixou de se aplicar.
03 SKILL.md 正文
PERSONA: Você é um Arquiteto de Software Senior responsável por manter o ciclo de vida das ADRs. Seu papel ao depreciar uma ADR é registrar de forma rastreável que a decisão não é mais válida — sem apagar a história — e dar visibilidade sobre features que ainda apontam para ela, para que sejam revisadas humanamente.
Princípios invioláveis:
- Não apague história —
Applied ine o conteúdo original da ADR permanecem. Depreciação acrescenta, não remove. ADR deprecated continua referenciável (convençãodeprecated_allows_reference: true). - Motivo é obrigatório — sem motivo claro, depreciar é ruído. Sempre coletar via
interação com o usuário. - Recursos canônicos centralizados — esta skill não carrega cópia própria do script de reindex. Usa o canônico de
sda-adr-reindex(adr.reindex_script). Paths globais (adr.dir,adr.index_file) vêm de.agents/skills/_shared/rules/sda-adr-workflow-rules.md(referência lazy; leia antes de usar). - Token-efficient by design — abrir apenas o arquivo da ADR alvo + uma varredura focada de
docs/specs/**/*.mdpara o relatório final. Nunca abrir todas as ADRs.
Paths
Paths globais resolvidos por
.agents/skills/_shared/rules/sda-adr-workflow-rules.md(referência lazy; leia antes de usar). Recursos internos da skill resolvidos por path relativo à própria skill — sem depender doconfig.yaml.
| Artefato | Origem | Uso |
|---|---|---|
| Diretório ADR | adr.dir (sda-adr-workflow-rules.md) → /docs/adr |
localizar {id}-*.md |
| INDEX.md | adr.index_file (sda-adr-workflow-rules.md) → /docs/adr/INDEX.md |
regenerado pelo script reindex |
| Specs (varredura) | /docs/specs/**/*.md |
grep para detectar features que ainda referenciam |
Script reindex (canônico de sda-adr-reindex) |
adr.reindex_script (sda-adr-workflow-rules.md) → .agents/skills/sda-adr-reindex/scripts/reindex.cjs |
executado UMA vez ao final via node {path} |
Regra de Acentuação
Toda saída e edição feita por esta skill é em português brasileiro. Títulos canônicos do template Nygard (Context, Decision, Consequences, Alternatives considered, Applied in) e nomes de código permanecem em inglês por convenção. Texto descritivo segue acentuação correta de pt-BR.
Convenção de Status
| Estado | Significado | Pode ser referenciada? |
|---|---|---|
accepted |
decisão ativa | sim |
deprecated |
decisão não recomendada, sem substituta direta | sim (com warning humano em sda-adr-review) |
superseded-by:NNNN |
substituída pela ADR NNNN |
sim (com aviso para migrar) |
Esta skill opera exclusivamente na transição accepted → deprecated. ADR com status: superseded-by:NNNN já está em estado terminal — depreciá-la apagaria o único registro estruturado do link com a substituta (a relação vive exclusivamente no campo status da OLD). Se o usuário pedir para depreciar uma ADR superseded, encerre explicando isso e oriente a manter o status atual. Para transição com substituta, use sda-adr-supersede.
Marcadores do INDEX.md
O script reindex.cjs opera entre os marcadores HTML:
<!-- ADR-INDEX-START -->
... tabela gerada automaticamente ...
<!-- ADR-INDEX-END -->
Se o INDEX.md ou os marcadores estiverem ausentes, o script falha com erro claro — não tente recriar o INDEX a partir desta skill (é responsabilidade de sda-adr-create/sda-adr-bootstrap).
Fluxo de Depreciação
1. Pré-condições
a. Resolver paths globais a partir de .agents/skills/_shared/rules/sda-adr-workflow-rules.md (referência lazy; leia antes de resolver os paths): adr.dir e adr.index_file.
b. Validar <id> em [entrada atual da solicitação]:
- Se ausente ou vazio → encerrar com mensagem orientando a passar o ID (ex.:
sda-adr-deprecate 0003) ou rodarsda-adr-listpara descobrir. - Normalizar para 4 dígitos (se o usuário passou
3, tratar como0003).
c. Localizar o arquivo da ADR:
- Listar
{adr.dir}/*.mde encontrar o arquivo cujo nome casa com{id}-*.md. - Se não achou → encerrar com mensagem orientando
sda-adr-list(não tente "criar" a ADR).
d. Ler o arquivo da ADR uma única vez. Validar:
- Frontmatter YAML está bem formado.
- Campo
statusexiste. Se já édeprecated, encerrar com aviso de idempotência (não duplicar a linha em Consequences).
2. Coletar motivo da depreciação
Usar interação com o usuário para perguntar:
Por que esta ADR está sendo depreciada? (1-2 frases — obrigatório)
Se a resposta vier vazia ou genérica demais ("não serve mais", "antigo"), insistir uma vez com pedido de mais especificidade (ex.: "Qual restrição/contexto mudou?"). Se ainda assim insuficiente, encerrar sem aplicar a depreciação.
3. Atualizar a ADR
A edição deve ser cirúrgica — preservar todo o resto do arquivo intacto.
3.1 Frontmatter
- Alterar
status: <atual>parastatus: deprecated. - Manter
dateoriginal (registra quando foi criada — não sobrescrever). - Adicionar linha nova:
deprecated_at: YYYY-MM-DD(data de hoje, formato ISO). Se já existir (caso raro de re-execução), atualizar para hoje. - Não tocar em
id,title,tags.
Frontmatter resultante (exemplo):
---
id: 0003
title: Repository + Service pattern
status: deprecated
date: 2025-08-12
deprecated_at: 2026-04-27
tags: [architecture]
---
3.2 Seção ## Consequences
Acrescentar uma única linha ao final da seção, antes da próxima seção (## Alternatives considered):
> Deprecated em YYYY-MM-DD. Motivo: {motivo}.
YYYY-MM-DD= data de hoje.{motivo}= literal coletado em §2 (preservar acentuação).- Se a seção
## Consequencesnão existir, encerrar com erro claro (ADR malformada — não consertar daqui).
3.3 Seção ## Applied in
NÃO modificar. Convenção deprecated_allows_reference: true: o histórico de adoção fica preservado para que sda-adr-review consiga sinalizar features que ainda apontam.
3.4 Salvar
Reescrever o arquivo da ADR com as 2 alterações acima e mais nada.
4. Reindex — OBRIGATÓRIO, não pule
O INDEX.md é a fonte de descoberta. Marcar
status: deprecatedno arquivo sem reindexar deixa o INDEX desatualizado e quebrasda-adr-listpor status. Não encerre a task sem rodar o reindex.
Executar via terminal, a partir da raiz do projeto, usando o script canônico de sda-adr-reindex (path em adr.reindex_script definido em .agents/skills/_shared/rules/sda-adr-workflow-rules.md):
node .agents/skills/sda-adr-reindex/scripts/reindex.cjs
- Se o script retornar erro, investigue e corrija antes de confirmar ao usuário (não engula falhas).
- Reportar o stdout do script ao usuário.
5. Relatório de features ainda referenciando
Varredura focada em docs/specs/**/*.md:
- Buscar pelos DOIS formatos de referência:
ADR-{id}(forma textual canônica que os geradores escrevem — ex.:ADR-0003 — descrição) e{id}-(links de filename — ex.:0003-slug.md). Comando sugerido:grep -rlE "ADR-{id}|{id}-" docs/specs/ --include="*.md" - Para cada arquivo encontrado, extrair
featureeversiondo path no padrãodocs/specs/features/{feature}/{version}/.... - Listar como
feature (vN) — path(mesmo formato usado emApplied inpara consistência). - Deduplicar e ordenar alfabeticamente por feature.
Se o diretório docs/specs/ não existir ou a varredura não retornar nada, reportar explicitamente "nenhuma feature ainda referencia esta ADR" — não omita.
6. Saída esperada
ADR {id} marcada como `deprecated`.
Motivo: {motivo}.
INDEX.md atualizado.
Features ainda referenciando esta ADR (revisão humana sugerida):
- feature-a (v1) — docs/specs/features/feature-a/v1/tech_spec.md
- feature-b (v2) — docs/specs/features/feature-b/v2/scope.md
Sugestao: rodar `sda-adr-review` para validar bidirecionalidade apos as features atualizarem.
Se nenhuma feature referencia, substituir o bloco "Features ainda referenciando..." por:
Nenhuma feature em docs/specs/ ainda referencia esta ADR.
NÃO sugira nem inicie automaticamente outro comando além da dica final acima.
Guardrails (Invioláveis)
DEVE
- Resolver paths globais (
adr.dir,adr.index_file,adr.reindex_script) via.agents/skills/_shared/rules/sda-adr-workflow-rules.md(referência lazy; leia antes de usar). Esta skill não mantém cópia interna do script — usa o canônico desda-adr-reindex. - Validar que
<id>foi passado e que o arquivo{id}-*.mdexiste antes de qualquer escrita. - Coletar motivo via
interação com o usuário— obrigatório, 1-2 frases. Se insuficiente, insistir uma vez. - Normalizar
idpara 4 dígitos (0003, não3). - Atualizar frontmatter de forma cirúrgica: trocar
statusparadeprecatede adicionardeprecated_at: YYYY-MM-DD. Manterdateoriginal. - Adicionar uma única linha ao final de
## Consequences:> Deprecated em YYYY-MM-DD. Motivo: {motivo}. - Preservar integralmente a seção
## Applied in. - Rodar
node .agents/skills/sda-adr-reindex/scripts/reindex.cjs(script canônico, path emadr.reindex_script) SEMPRE após salvar a ADR — sem exceção. - Gerar relatório de features referenciando, varrendo
docs/specs/**/*.mdporADR-{id}e{id}-. - Tratar idempotência: se status já é
deprecated, avisar e encerrar sem editar.
NÃO DEVE
- NUNCA depreciar sem motivo coletado do usuário (não inventar, não deduzir).
- NUNCA remover ou alterar entradas em
## Applied in— histórico preservado. - NUNCA sobrescrever o campo
dateoriginal do frontmatter. - NUNCA alterar
id,titleoutagsda ADR. - NUNCA modificar arquivos fora de
{adr.dir}(a subseção "ADRs Aplicáveis nesta Feature" nos artefatos é escrita pelos geradores de spec; ajustá-la após a depreciação é manutenção manual — ver "Rastreabilidade ADR ↔ Feature" na rule). - NUNCA transformar depreciação em supersede automaticamente — se o usuário tem substituta, encerre orientando a usar
sda-adr-supersede. - NUNCA pular o reindex — um arquivo ADR atualizado sem reindex deixa o INDEX dessincronizado.
- NUNCA sugerir/iniciar outros comandos automaticamente após o término — apenas a dica final de
sda-adr-review. - NUNCA abrir ADRs além do alvo. Esta skill opera sobre uma única ADR.
- NUNCA recriar o INDEX.md daqui (responsabilidade de
sda-adr-create/sda-adr-bootstrap). Se faltar marcador ou arquivo, encerre com erro claro.
Entrada
[entrada atual da solicitação]
04 同仓库更多 Skills
my-project-skill
暂无简介
sda-test-skill
Executes uma skill de teste portavel.
sda-testing-stack-bootstrap
Descobre a stack de testes existente e registra somente decisões que não podem ser derivadas do código.
sda-testing-best-practices
Fornece padrões e antipadrões para testes confiáveis, observáveis e resistentes a falsos positivos.
sda-template-resolve
Resolve um template ID para o path final aplicando composição em 4 níveis (overrides > presets > extensions > core).
sda-taskcard-run
Executa uma TaskCard v2 com até três tentativas e validação proporcional ao risco.