tech-radar

name	tech-radar
description	Descobre tecnologias em um ou mais repositórios, produz inventário rastreável, propõe blips para um Technology Radar e conduz a aprovação humana antes de publicar anéis oficiais. Use quando o usuário pedir para gerar, atualizar, revisar, classificar ou exibir um tech radar a partir de código real.

Technology Radar

Orquestre um pipeline no qual scripts coletam e consolidam fatos, a IA propõe posturas e o humano toma as decisões. Nunca grave dados de execução dentro da pasta da skill ou do plugin.

Esta skill é a interface do usuário. Execute os scripts internamente; não instrua o usuário a operar Node ou terminal, salvo quando ele pedir troubleshooting ou detalhes de desenvolvimento.

Contrato essencial

• Trate null como não medido, nunca como zero ou ausência.
• Baseie propostas somente nos YAMLs do diretório de dados e nas referências.
• Grave julgamento da IA em proposed_*; nunca grave ring em nome do usuário.
• Registre propostas somente com record-proposals.mjs; não edite YAML de blip diretamente nem altere campos oficiais durante a classificação.
• No repositório central, nunca edite campos oficiais diretamente: crie uma ADR, ratifique-a e aplique-a pelo script.
• Preserve decisões aprovadas em novas execuções e marque needs_review quando os fatos mudarem.
• Interrompa o fluxo quando scan.mjs ou validate.mjs falhar.

Leia antes de classificar:

• references/rings.md
• references/heuristics.md
• references/signals-guide.md
• references/rationale-style.md

Leia references/contracts.md antes de criar config.yaml ou editar blips.

Portabilidade

Use os recursos equivalentes disponíveis no ambiente:

• Solicitar dados ou decisões: ferramenta de interação estruturada, se houver; caso contrário, chat normal.
• Executar scripts: shell disponível, sem assumir um nome específico de ferramenta.
• Entregar HTML: mecanismo de apresentação de arquivos, se houver; caso contrário, caminho local clicável.

Resolva <skill> como a pasta que contém este SKILL.md. Exija Node.js 18 ou superior.

Diretório de dados

Prefira a raiz do repositório central indicada pelo usuário. Quando existir architecture.yaml, os scripts resolvem automaticamente o layout:

architecture-data/
  architecture.yaml
  radar/config.yaml
  radar/inventory/<repo-id>.yaml
  radar/blips/<slug>.yaml
  cache/tech-radar/
  generated/radar/radar.yaml
  generated/radar/tech-radar-proposals.html
  generated/radar/tech-radar.html

Para compatibilidade, um diretório sem architecture.yaml continua sendo interpretado como o layout legado:

radar-data/
  config.yaml
  inventory/<repo-id>.yaml
  blips/<slug>.yaml
  cache/
  radar.yaml
  out/tech-radar-proposals.html
  out/tech-radar.html

Pipeline

1. Preparar

Se <data>/radar/config.yaml (central) ou <data>/config.yaml (legado) não existir, solicitar título, IDs seguros e caminhos absolutos dos repositórios. Criar o arquivo conforme references/contracts.md.

2. Coletar fatos

Executar:

node <skill>/scripts/scan.mjs --data-dir <data>

Reportar repositórios, ocorrências e warnings. Não prosseguir se algum repositório estiver inacessível ou tiver ID inválido.

3. Enriquecer

Executar enrich.mjs. Se a rede estiver indisponível, tentar o cache com --offline e declarar explicitamente quais sinais ficaram não medidos. Nunca completar fatos por memória ou pesquisa livre.

4. Consolidar

Executar:

node <skill>/scripts/merge.mjs --data-dir <data>

O script preserva ocorrências por projeto, calcula cobertura e invalida propostas quando os fatos mudam. Não reproduzir o merge manualmente.

5. Propor anéis

Para cada blip ativo sem proposta válida:

1. Ler os fatos do próprio blip.
2. Preencher proposed_ring, proposed_confidence e proposed_rationale.
3. Preencher proposal_evidence somente com caminhos como signals.project_count, signals.advisory.max_severity e occurrences[0].source_file que existam no YAML.
4. Manter decision_status: proposed e ring: null.

Processar internamente em lotes pequenos, mas cobrir todos os blips ativos antes de apresentar o resultado ao usuário. Não alterar fatos, decisões humanas ou blips inativos.

Para cada lote, gerar um JSON temporário no contrato documentado em references/contracts.md e executar:

node <skill>/scripts/record-proposals.mjs --data-dir <data> --input <proposals.json>

O script verifica o facts_hash, as referências de evidência e restringe a escrita aos quatro campos proposed_*. Se os fatos mudaram, refazer a recomendação.

6. Validar

Executar validate.mjs. Corrigir propostas sem evidência ou contratos inválidos antes de apresentar qualquer resultado.

7. Apresentar e aguardar

Renderizar somente quando todos os blips ativos possuírem proposta válida. Apresentar uma visão completa agrupada por anel recomendado, confiança e risco, sempre mostrando lacunas e dados não medidos. Não escolher, sugerir ou priorizar um blip para revisão. Depois da apresentação, aguardar o usuário indicar o que deseja revisar.

8. Revisar com o humano

Apresentar primeiro propostas de baixa confiança e casos com risco. Para cada decisão explícita no repositório central:

1. Criar a proposta com write-adr/scripts/create-radar-adr.mjs.
2. Completar racional, alternativas, trade-offs, consequências, riscos, revisão e decisores.
3. Validar e alterar a ADR para accepted somente quando o gate passar.
4. Executar:

node <skill>/scripts/apply-adr.mjs --data-dir <data> --adr <adr.yaml>

O comando rejeita ADR proposta/inválida, detecta movimento concorrente e grava decision_adr e decision_history. No layout legado, os campos podem continuar sendo preenchidos diretamente até a migração para um repositório central.

Operações governadas:

• Aprovar: ADR com radar_change.action: approve e to_ring.
• Rejeitar: ADR com radar_change.action: reject e to_ring: null.
• Mover: ADR com radar_change.action: move, from_ring e to_ring.
• Adiar: manter decision_status: proposed.

Não interpretar silêncio, aceite genérico do relatório ou pedido de render como aprovação dos anéis.

9. Renderizar

Gerar propostas:

node <skill>/scripts/render.mjs --data-dir <data> --mode proposed

Esse modo recusa por padrão conjuntos incompletos. --allow-incomplete existe somente para desenvolvimento e diagnóstico; nunca usar para apresentar o resultado da análise ao participante.

Gerar somente decisões aprovadas:

node <skill>/scripts/render.mjs --data-dir <data> --mode approved

Entregar os caminhos e informar quantos blips foram descobertos, propostos, aprovados e omitidos.

10. Atualizar o grafo

No repositório central, execute após aplicar decisões ou renderizar o Radar:

node <skill>/../../shared/scripts/generate-graph.mjs --data-dir <data>

Entregue o JSON, o HTML e os erros/alertas de integridade. Não trate warning de cadeia incompleta como relação inexistente; informe-o como trabalho de governança.