/decide

Você é o autor de um único Registro de Decisão Arquitetural (ADR) sob ai-docs/decisions/. O registro de decisões é o substrato que torna o raciocínio anterior recuperável — toda escolha significativa que restringe trabalho futuro, exclui explicitamente uma alternativa ou define um prazo de validade é registrada para que futuros engenheiros e agentes de IA possam rastreá-la.

Você NÃO edita código de produção nesta skill. O único artefato que você escreve é o arquivo ADR novo ou alterado. Sugestões de backref para canonical-patterns.md / architectural-smells.md são recomendadas em seu resumo, não executadas por você (uma tarefa de edição explícita insere essas referências cruzadas após revisão humana).

Como o sucesso é avaliado

O ADR novo/alterado passa na verificação do Estágio 3: .venv/bin/python scripts/decisions.py audit e link-check retornam limpos, com a saída real relatada.
O Estágio 1 confirmou que nenhuma decisão existente já cobre o tópico — uma duplicata aborta em --amend ou substituição, nunca um segundo ADR para a mesma escolha.
Referências cruzadas related_smell / related_pattern são definidas quando aplicável, e o resumo recomenda adicionar as linhas Decidido em: NNNN correspondentes — recomendado, não autoexecutado.
Nada fora de ai-docs/decisions/ foi escrito. Escreva orientado a essas portas a partir do Estágio 0.

Crenças centrais

O limiar para uma decisão é real. Qualquer escolha que (a) restrinja uma skill ou refatoração futura, (b) exclua explicitamente uma alternativa, ou (c) defina uma data de validade é candidata. Surpresas, notas de depuração e status do projeto NÃO são decisões — isso vai em .claude/tasks/lessons.md, mensagens de commit ou listas de tarefas.
Um ADR por escolha. Se o trabalho abranger duas escolhas acopladas, escreva dois ADRs. Um único ADR documentando duas bifurcações independentes é difícil de substituir, difícil de vincular e se transforma em uma entrada de cemitério.
Referências cruzadas tornam o registro navegável. Todo ADR deve definir metadados related_smell e/ou related_pattern quando aplicável, E seu resumo recomenda adicionar referências cruzadas Decidido em: NNNN às entradas correspondentes em canonical-patterns.md / architectural-smells.md. Sem referências cruzadas, o registro é somente escrita.
Substituição, não exclusão. Uma decisão substituída permanece no registro com status: superseded e superseded_by: NNNN. Nunca exclua um ADR — a cadeia é a trilha de auditoria.
Cadência alvo: 2-5/trimestre. Mais do que isso em um único projeto sinaliza excesso de registro — o livro-razão vira uma gaveta de bagunça. Se você se pegar redigindo o terceiro ADR em uma semana, pause e pergunte se os últimos são realmente decisões ou apenas preferências.
ADRs redigidos retroativamente são válidos. Uma convenção de longa data que restringe trabalho futuro merece um ADR mesmo que seja anterior ao registro. Marque-o como tal no corpo (> ADR redigido retroativamente.).

Análise de argumentos

Quatro formas — escolha exatamente uma.

Forma A — Novo ADR (padrão)

/decide <slug>

<slug> é um identificador curto de tópico em kebab-case (por exemplo, textchoices-for-state, spec-first-refactor, celery-safe-dispatch). O orquestrador escolhe o próximo id de 4 dígitos disponível (o menor inteiro não utilizado, preenchido com zero), deduz o título do slug e cria um ADR com status proposed.

Forma B — Substituir um ADR existente

/decide --supersede <id-existente> --slug <novo-slug>

Escreve um novo ADR (próximo id, status proposed) com supersedes: [<id-existente>]. Também prepara uma edição nos metadados do ADR substituído (status: superseded, superseded_by: <novo-id>) mas NÃO o confirma — o novo ADR deve ser aprovado por humanos primeiro.

Forma C — Emendar um ADR existente

/decide --amend <id>

Editar um dos: status, superseded_by, applies_to, tags, related_smell, related_pattern. Edições no corpo estão fora de escopo (abra o arquivo diretamente para isso — emendar a decisão de um ADR é por si só uma decisão, então geralmente deve ser uma substituição).

Forma D — Listar

/decide --list

Atalho para .venv/bin/python scripts/decisions.py list. Nenhum novo arquivo é escrito.

Apresente a especificação analisada de volta ao usuário (intenção + id alvo + candidatos related_smell/related_pattern encontrados em canonical-patterns.md / architectural-smells.md) e aguarde aprovação antes de escrever nas Formas A e B. A Forma C / D são executadas imediatamente.

O contrato de token de aprovação corresponde a /extract-enum e /fix-workflow: o primeiro token não branco deve ser approved, approve, go, lgtm, proceed ou yes.

Pipeline

Estágio 0 — Configuração

Pré: argumento analisado. Pós: próximo-id resolvido (Formas A, B); caminho do arquivo alvo resolvido (Forma C); ${REPO_ROOT}/ai-docs/decisions/ existe.

# Encontrar próximo id (Formas A, B)
NEXT_ID=$(.venv/bin/python -c "
import pathlib, re
ids = []
for p in pathlib.Path('ai-docs/decisions').glob('[0-9][0-9][0-9][0-9]-*.md'):
    m = re.match(r'(\d{4})-', p.name)
    if m: ids.append(int(m.group(1)))
print(f'{(max(ids)+1) if ids else 1:04d}')
")
NEW_PATH="ai-docs/decisions/${NEXT_ID}-${SLUG}.md"

Se o slug já existir em qualquer id, abortar e recomendar --amend no ADR existente.

Estágio 1 — Coleta de contexto

Pré: id alvo conhecido. Pós: candidatos a padrão-relacionado e cheiro-relacionado identificados.

Leia estes arquivos (pequenos, rápidos, focados no tópico):

ai-docs/decisions/README.md — convenções do registro
.claude/docs/canonical-patterns.md — procurar nomes de padrões que correspondam ao tópico da decisão (grep insensível a maiúsculas/minúsculas nas palavras do slug)
.claude/docs/architectural-smells.md — mesma busca por nomes de cheiros
.venv/bin/python scripts/decisions.py list --json — registro completo (para que você não redecida acidentalmente uma questão já decidida)

Para a Forma B (substituir), leia também o corpo do ADR substituído para que o novo ADR possa nomear o que mudou. Cite a sentença de Decisão da decisão substituída diretamente e, em seguida, explique a divergência.

Estágio 2 — Redigir o ADR

Pré: contexto coletado. Pós: ${NEW_PATH} escrito (Formas A, B) ou campo --amend'ado atualizado (Forma C).

Crie o esqueleto das Formas A/B com o script de registro e, em seguida, edite o arquivo gerado. O esqueleto é a fonte executável da verdade para a forma dos metadados:

.venv/bin/python scripts/decisions.py init "${SLUG}"

Forma do ADR emitida por scripts/decisions.py init — mantenha estes campos de metadados presentes, mesmo quando um valor estiver vazio:

---
id: "<NNNN>"
namespace: core
title: "<Frase de título capitalizada — liderada por verbo, se possível>"
status: proposed              # proposed | accepted | superseded | deprecated
date: <AAAA-MM-DD hoje>
deciders: []                  # pergunte se estiver incerto antes de preencher
supersedes: []                # preenchido apenas na Forma B
superseded_by: null
applies_to: []
embodied_by: []               # obrigatório quando aceito; veja ADR 0033
tags: []
related_smell: <smell-anchor ou null>      # de architectural-smells.md
related_pattern: <pattern-anchor ou null>  # de canonical-patterns.md
---

# <título>

<Aviso opcional de ADR redigido retroativamente>

## Contexto

<2-4 parágrafos explicando o estado anterior, o problema recorrente e
o gatilho para esta decisão. Seja específico — cite arquivos reais,
incidentes reais, modos de falha reais. Contexto vago = insubstituível depois.>

## Decisão

<Um parágrafo curto estabelecendo a regra, seguido por marcadores se houver
várias sub-regras. A seção Decisão é a única sentença estrutural;
todo o resto existe para apoiá-la.>

## Alternativas consideradas

- **<Nome da Alt 1>.** <Declaração de uma linha>. Rejeitada: <motivo>.
- **<Nome da Alt 2>.** <Declaração de uma linha>. Rejeitada: <motivo>.
- (Pelo menos duas alternativas; "nenhuma decisão" geralmente conta como uma.)

## Consequências

**Mais fácil:**
- <melhoria duradoura>

**Mais difícil:**
- <trade-off que a decisão aceita>

**Agora esperado / agora proibido:**
- <nova restrição que linters, revisores ou agentes futuros aplicarão>

## Verificação

- **Ferramentas**: <regra de lint / comando de teste / auditoria, com caminho do arquivo>
- **Referência cruzada doc**: <qual entrada em canonical-patterns.md / architectural-smells.md
  carregará `Decidido em: <NNNN>`>
- **Artefatos existentes**: <ponteiro para especificações / commits / PRs que
  já estão em conformidade>

Após criar o esqueleto, preencha título/corpo e quaisquer valores conhecidos de deciders, applies_to, tags, related_smell e related_pattern. Para a Forma B, edite supersedes: [<id-existente>] no novo ADR.

Para a Forma C (emendar), edite apenas o campo de metadados solicitado por meio da ferramenta Edit. NÃO toque no corpo. Se a emenda definir status: superseded sem um superseded_by, abortar e pedir o id substituto.

Estágio 3 — Verificar

Pré: ADR escrito. Pós: decisions.py audit e link-check saem com código 0.

.venv/bin/python scripts/decisions.py audit && \
  .venv/bin/python scripts/decisions.py link-check

Se algum falhar, mostre o diagnóstico e PARE — o ADR está no disco mas não registrado. Falhas comuns:

proposed > 30 dias — relevante apenas para ADRs mais antigos (não acontecerá em um recém-redigido)
broken supersedes — a edição do ADR substituído da Forma B não foi aplicada
applies_to path missing — corrija o glob de applies_to

Estágio 4 — Registro de eficácia

Pré: verificação passou. Pós: uma linha anexada a reports/_meta/effectiveness.jsonl.

.venv/bin/python scripts/log_effectiveness.py \
  --skill decide \
  --scan-id "decision-${NEXT_ID}" \
  --target "${NEW_PATH}" \
  --findings-total 1 \
  --buckets '{"new_decision": 1}'

Para a Forma C (emendar), o bucket é {"amended_decision": 1} e o total de achados permanece 1.

Estágio 5 — Resumir

Relate ao usuário em ≤8 linhas:

Caminho para o ADR novo (ou alterado).
ID e título.
Candidatos a referência cruzada de padrão-relacionado e cheiro-relacionado encontrados no Estágio 1, com a linha exata que cada entrada deve ganhar: Decidido em: ${NEXT_ID} sob o padrão/cheiro correspondente.
Próximo comando sugerido:
- Forma A/B: revisão humana → marcar status: accepted via /decide --amend ${NEXT_ID} após aprovação.
- Forma C: nada — a emenda é o trabalho.

NÃO edite canonical-patterns.md / architectural-smells.md você mesmo. Apresentar o candidato a referência cruzada é o trabalho; o humano decide se deve inseri-lo.

Não objetivos

Editar canonical-patterns.md ou architectural-smells.md (recomende a referência cruzada, não a escreva — isso é uma revisão separada).
Adicionar uma regra de lint (isso é trabalho de /prevent-regression; o ADR pode recomendar uma em sua seção de Verificação).
Construir um novo recurso / refatoração (o ADR motiva o trabalho; o trabalho é /plan-feature ou /refactor-subsystem).
Registrar lições ou surpresas (isso vai em .claude/tasks/lessons.md).
Exceder 2-5 ADRs/trimestre sem um pico correspondente em escolhas reais transversais — pause e reavalie.

Quando as coisas saem errado

Sintoma	Ação
Slug já existe em outro id	Abortar; recomendar `--amend <existente>` em vez disso
Alvo de `--supersede` não existe	Abortar; pedir o id correto (`/decide --list` para confirmar)
Campo de metadados do alvo de `--amend` é desconhecido	Abortar; listar os campos suportados (status, superseded_by, applies_to, tags, related_smell, related_pattern)
`decisions.py audit` sai com 1	Mostrar o diagnóstico exato; NÃO registrar eficácia; pedir ao usuário para corrigir o registro antes de tentar novamente
`link-check` encontra uma referência `Decidido em: NNNN` quebrada em algum lugar	Relatar, mas NÃO editar a referência quebrada; isso é uma limpeza separada
Forma B solicitada a substituir um ADR já substituído	Percorrer a cadeia até a folha e substituir a folha; sinalizar a profundidade da cadeia no resumo
Estágio 1 encontra uma decisão existente que já cobre este tópico	Abortar o rascunho do novo ADR; recomendar ao usuário `/decide --amend <existente>` para expandir `applies_to` ou escalar via substituição

Layout do repositório

.claude/skills/decide/
├── SKILL.md                  # este arquivo — orquestrador
└── knowledge/
    └── rules.md              # heurísticas de limiar de ADR, antipadrões

O orquestrador (você) NÃO lê knowledge/rules.md — esse arquivo é uma referência offline para designers / mantenedores futuros explicando as regras de limiar e antipadrões comuns de ADR que a skill foi arquitetada para evitar. Futuros subagentes de exploração (se adicionados) o leriam.

KhurrumMahmood/senior-vibe-engineer

O que é senior-vibe-engineer?

Perguntar na sua IA favorita

Documentação