Reparo Mínimo de HDL e Verificação de Consistência
Um fluxo de trabalho para gerar o menor patch seguro que corrige um bug de design HDL, em seguida, verificar se a correção não quebra contratos de hardware ou deixa inconsistências entre artefatos.
O Que Este Skill Abrange
Este skill é a metade de reparo de um pipeline de dois skills (localização → reparo). Ele aceita dois caminhos de entrada:
- Com uma Nota de Hipótese de Causa Raiz (de
hdl-fault-localizationou equivalente) — analise a nota, selecione a melhor hipótese e prossiga. - Com uma intenção de reparo existente — quando o usuário ou um agente anterior já definiu um local específico do bug, direção da correção ou diff de patch, promova essa intenção para uma hipótese provisória e prossiga.
O skill faz quatro coisas e nada mais:
- Planejamento de patch mínimo — o menor conjunto de alterações que resolvem a hipótese selecionada, sem modificações não relacionadas.
- Scanner de Efeitos Colaterais — verificação de pares de contratos de hardware (ready/valid, reset/flush/replay, transições FSM, estado obsoleto, ordenação pipeline).
- Verificador de Links de Artefatos — garantia de que configurações, arquivos gerados, descrições de registradores e scripts geradores permaneçam consistentes.
- Verificação de teste — execução do conjunto de testes e tratamento de falhas via hipóteses de fallback.
Este skill NÃO realiza localização de falhas. Se o bug não foi localizado, pare e exija localização primeiro.
Quando Usar Este Skill
Este skill é ativado somente quando o problema já foi localizado. Qualquer um dos seguintes é suficiente para entrada:
- Uma Nota de Hipótese de Causa Raiz é fornecida (de
hdl-fault-localizationou equivalente). - O usuário ou um agente anterior forneceu um local explícito do bug (arquivo, módulo, sinal) e direção da correção (o que mudar e por quê).
- O usuário declarou uma intenção de reparo clara (por exemplo, "alargar este ponteiro", "adicionar um buffer skid", "corrigir a transição FSM").
- Um diff de patch existente precisa ser revisado para efeitos colaterais ou consistência.
Se nenhum desses sinais de entrada estiver presente — o bug não está localizado, não há hipótese e não há intenção de reparo específica para promover — pare e exija localização primeiro. Não tente diagnosticar o bug; essa é a responsabilidade de um skill separado de localização de falhas. Solicitações vagas como "corrigir este bug", "algo está errado" ou "meu testbench falha" sem qualquer informação de localização NÃO são sinais de entrada — elas carecem da especificidade exigida para o escopo somente de reparo deste skill.
Frases típicas de acionamento: "aplicar a correção", "fazer o patch", "implementar o reparo", "verificar este patch para efeitos colaterais", "verificar contratos de hardware após esta alteração", "auditar consistência entre artefatos".
Requisitos de Entrada
Pelo menos um dos seguintes deve estar presente antes de começar. Se nenhum existir, pare e exija localização primeiro.
- Nota de Hipótese de Causa Raiz — um arquivo ou texto inline descrevendo uma ou
mais hipóteses, cada uma com força da evidência e justificativa. Esta é a
entrada preferida e é produzida por
hdl-fault-localization. - Local explícito do bug + direção da correção — o usuário ou agente anterior identificou um arquivo, módulo ou sinal específico e descreveu qual alteração fazer. Promova essa intenção de reparo para uma hipótese provisória.
- Intenção de reparo existente — um plano declarado (por exemplo, "alargar o ponteiro de 4 para 5 bits") que pode ser tratado como uma nota de hipótese única.
- Diff de patch existente — uma alteração de código proposta para revisão de efeitos colaterais e consistência de artefatos.
Além disso, reúna:
- Arquivos fonte relevantes — caminhos para os módulos HDL, testbenches e código de suporte envolvidos.
- Comando de teste — o comando exato para executar o conjunto de testes.
- Logs de falha — opcionais, mas recomendados para contexto.
Fluxo de Trabalho Principal
Siga estas etapas em ordem. Cada etapa produz saída que alimenta a próxima.
Etapa 0: Verificação de Portão de Entrada (ANTES de qualquer análise de código)
Antes de ler qualquer arquivo fonte, logs ou formas de onda, verifique se pelo menos um sinal de entrada está presente na mensagem do usuário. Verifique nesta ordem:
- Existe uma Nota de Hipótese de Causa Raiz (um caminho de arquivo, YAML inline, ou texto estruturado com hipóteses e evidências rotuladas)?
- O usuário especificou um local concreto do bug e direção da correção (um arquivo, módulo ou sinal específico E uma descrição de qual alteração fazer — não apenas "corrigir" ou "algo está errado")?
- O usuário declarou uma intenção de reparo específica (por exemplo, "alargar o ponteiro para 5 bits", "adicionar um buffer skid", "alterar a transição FSM de A para B")?
- Existe um diff de patch existente para revisar?
Se NENHUM destes estiver presente — o usuário diz apenas "corrigir este bug", "meu testbench falha", "algo está errado" ou solicitações vagas semelhantes sem localização — pare imediatamente. Não leia o código fonte. Não tente diagnosticar o bug. Saída:
Este skill requer localização prévia. Por favor, execute a localização de falhas
primeiro (hdl-fault-localization), ou forneça um dos seguintes:
- Uma Nota de Hipótese de Causa Raiz
- Um local explícito do bug (arquivo/módulo/sinal) e direção da correção
- Uma intenção de reparo específica (o que mudar e por quê)
- Um diff de patch existente para revisar
Somente prossiga para a Etapa 1 após confirmar que um sinal de entrada está presente.
Etapa 1: Estabelecer a Hipótese de Reparo
Se uma Nota de Hipótese de Causa Raiz formal estiver disponível, analise-a para extrair:
- Cada hipótese, rotulada e descrita.
- A evidência que suporta cada hipótese (forte, moderada, fraca).
- A direção de correção sugerida para cada hipótese.
- Qualquer ordenação de fallback ou dependência entre hipóteses.
Se a nota contiver várias hipóteses, liste todas. Se contiver apenas uma, isso simplifica a seleção — mas ainda avalie a força de sua evidência antes de se comprometer.
Se nenhuma nota de hipótese for fornecida, mas existir uma intenção de reparo (local explícito do bug + direção da correção, um plano de reparo declarado ou um diff de patch existente), promova essa intenção para uma hipótese provisória. Dê a ela um rótulo (por exemplo, "P1-sync-fifo-pointer-widen") e documente a evidência que a suporta a partir da descrição do usuário. Esta hipótese provisória é tratada como a única hipótese para as Etapas 2-7. Não tente gerar hipóteses alternativas ou realizar localização de falhas — o escopo deste skill termina na execução do reparo.
Etapa 2: Selecionar a Melhor Hipótese para Patch Primeiro
Nem todas as hipóteses são iguais. Aplique estes critérios de seleção:
- Força da evidência — prefira hipóteses com evidência concreta (traços de formas de onda, padrões de log, condições reproduzíveis) em vez de especulativas.
- Risco do patch — prefira hipóteses cuja correção seja localizada (um ou dois módulos, sem alterações estruturais) em vez daquelas que exigem reescritas extensas.
- Reversibilidade — prefira hipóteses cujo patch seja fácil de reverter se não funcionar.
- Ordem de dependência — se a Hipótese B depende da Hipótese A estar correta, faça o patch de A primeiro.
Documente por que você escolheu esta hipótese em vez das alternativas. Se você não conseguir decidir entre duas hipóteses igualmente fortes, escolha aquela com menor risco de patch e anote a outra como o fallback primário.
Etapa 3: Gerar um Plano de Patch Mínimo
Um "patch mínimo" não significa "alterar apenas um arquivo." Significa: o menor conjunto de alterações que corrige corretamente a hipótese selecionada, com nenhuma modificação não relacionada.
Para cada arquivo que você planeja modificar, responda:
- Por que este arquivo deve mudar? — trace a cadeia causal da hipótese até esta alteração específica.
- O que exatamente muda? — descreva a alteração no nível do sinal/lógica, não detalhes de implementação.
- Por que esta é a alteração mínima? — explique por que uma alteração menor seria insuficiente ou uma alteração maior desnecessária.
Rejeite qualquer alteração que:
- Seja cosmética (formatação, renomeação, atualizações de comentários não relacionadas ao bug).
- Seja uma refatoração ("já que estou aqui, deixe-me limpar isso").
- Hardcode uma expectativa de teste para fazer um teste passar.
- Modifique um arquivo de teste sem evidência de que o teste em si está errado.
Etapa 4: Executar o Scanner de Efeitos Colaterais
Designs de hardware têm contratos implícitos entre sinais. Alterar um lado de um contrato frequentemente quebra o outro lado. Antes de aplicar o patch, verifique por estas violações de contrato:
Pares ready/valid
Para cada par de handshake ready/valid no módulo modificado e seus
vizinhos imediatos:
- O patch altera quando
validé afirmado ou desassertado? Se sim, a lógicareadydo consumidor ainda funciona corretamente? - O patch altera quando
readyé amostrado ou acionado? Se sim, a lógicavaliddo produtor ainda faz sentido? - A contrapressão ainda é tratada corretamente — o pipeline pode parar sem perder dados?
Reset/flush/replay
Para cada sinal de reset, flush ou replay:
- O patch altera qual estado é limpo ou preservado no reset?
- Um caminho de flush ainda drena ou invalida dados em voo corretamente?
- Um caminho de replay ainda restaura o estado para o checkpoint correto?
Completude de transição FSM
Para cada máquina de estados finita tocada pelo patch:
- Todos os estados são alcançáveis a partir do reset?
- A FSM pode entrar em deadlock (nenhuma saída válida de um estado)?
- A FSM pode entrar em livelock (loop infinito entre estados sem progresso)?
- O patch adiciona ou remove alguma transição de estado? Se sim, verifique se a nova tabela de transições está completa.
Estado obsoleto
- O patch introduz algum registrador ou sinal que pode manter um valor obsoleto entre transações ou ciclos de clock onde deveria ser limpo?
- O patch depende de um sinal ser limpo por um mecanismo que não mais dispara corretamente?
Ordenação do pipeline
- O patch altera a ordem das operações em um pipeline? Se sim, os escadas a jusante ainda recebem dados na ordem esperada?
- O patch altera a profundidade do pipeline (estágios adicionados ou removidos)? Se sim, todos os caminhos de bypass e forwarding são ajustados?
Documente as descobertas para cada categoria, mesmo que o resultado seja "nenhum problema encontrado."
Etapa 5: Executar o Verificador de Links de Artefatos
Projetos HDL frequentemente têm arquivos de configuração, mapas de registradores e código gerado que devem permanecer sincronizados com o código fonte HDL. Verifique estes links:
Arquivos de configuração
Verifique arquivos de configuração (YAML, HJSON, JSON, TOML, INI ou semelhantes) que referenciam os sinais, parâmetros ou módulos tocados pelo patch. Se o patch alterar um valor de parâmetro, nome de módulo ou lista de portas, atualize a configuração para corresponder.
Arquivos gerados
Verifique se alguns arquivos no projeto são gerados automaticamente (por geradores de código, scripts ou etapas de build). Se o patch alterar uma fonte que alimenta um gerador, ou:
- Regere os arquivos de saída, ou
- Sinalize a inconsistência para regeneração manual.
Descrições de registradores
Se o design incluir um mapa de registradores (CSV, XML, IP-XACT, SystemRDL ou semelhante), verifique se as posições, larguras e tipos de acesso dos campos de registrador não se desviaram do HDL após o patch.
Scripts geradores
Verifique scripts Python, Perl, Tcl ou shell que geram HDL ou arquivos de configuração. Se o patch alterar um padrão no qual esses scripts dependem (convenções de nomenclatura, larguras de sinal, protocolos de interface), os scripts podem produzir saída quebrada.
Documente todos os artefatos verificados e quaisquer inconsistências encontradas.
Quando o patch altera apenas lógica interna (sem interfaces públicas, parâmetros, campos de registrador, mapas de endereços, fontes geradas ou comportamento visível em configuração), a verificação de link de artefato se reduz a "não aplicável — patch apenas interno sem impacto entre artefatos." Evite escanear toda a árvore do projeto em busca de artefatos que não podem ser afetados pela alteração. Execute uma busca completa de artefatos apenas quando o patch tocar uma das superfícies listadas acima.
Etapa 6: Aplicar o Patch e Executar Testes
Aplique o patch nos arquivos fonte reais. Em seguida, execute o comando de teste:
- Execute o conjunto de testes uma vez.
- Se todos os testes passarem — documente o resultado e prossiga para a Etapa 7.
- Se alguns testes falharem — analise:
- As falhas são pré-existentes? Verifique logs de falha para ver se esses testes falhavam antes do patch. Falhas pré-existentes não são culpa do patch — anote-as, mas não bloqueie a correção.
- As falhas são causadas pelo patch? Se o patch introduziu novas falhas, a correção está incompleta ou incorreta. Vá para o caminho de fallback.
- As falhas revelam um bug no teste? Conclua isso apenas se você tiver evidência concreta de que a expectativa do teste está errada, não apenas porque o patch alterou o comportamento.
Etapa 7: Lidar com Falha — Fallback para a Próxima Hipótese
Se o patch falhar nos testes de uma maneira que é causada pelo patch (não pré-existente ou bug de teste):
- Não tente salvar o patch com ajustes ad-hoc. Isso transforma uma correção baseada em hipótese em adivinhação.
- Se o ambiente de execução suportar rollback limpo (por exemplo,
git checkout,git stashou um harness externo gerenciando o estado do patch), reverta o patch falho antes de tentar o fallback. Se o rollback não for suportado, inspecione e desfaça explicitamente as edições falhas antes de continuar — não sobreponha um novo patch em cima de um quebrado. - Selecione a próxima hipótese da nota de hipótese (aquela com a próxima melhor combinação de evidência e risco).
- Documente na Nota de Decisão de Patch: qual hipótese falhou, por quê (qual teste quebrou) e qual hipótese está sendo tentada agora.
- Retorne à Etapa 2 com a hipótese de fallback.
Se todas as hipóteses forem esgotadas e nenhum patch passar nos testes, relate que o conjunto de hipóteses é insuficiente — a causa raiz pode não ser capturada por nenhuma das explicações hipotéticas.
Saída: Nota de Decisão de Patch
Ao final do fluxo de trabalho (quer o patch tenha sido bem-sucedido ou não), produza uma Nota de Decisão de Patch usando esta estrutura exata:
patch_decision_note:
selected_hypothesis: <qual hipótese foi corrigida>
patch_scope: <resumo de uma frase do que o patch altera>
modified_files:
- <caminho do arquivo>: <motivo pelo qual este arquivo teve que mudar>
- <caminho do arquivo>: <motivo pelo qual este arquivo teve que mudar>
side_effect_scan_results:
ready_valid: <nenhum problema encontrado ou lista de problemas>
reset_flush_replay: <nenhum problema encontrado ou lista de problemas>
fsm_transitions: <nenhum problema encontrado ou lista de problemas>
stale_state: <nenhum problema encontrado ou lista de problemas>
pipeline_ordering: <nenhum problema encontrado ou lista de problemas>
artifact_consistency_check:
config_files: <verificado — nenhuma alteração necessária ou alterações aplicadas>
generated_files: <verificado — nenhuma alteração necessária ou alterações aplicadas>
register_descriptions: <verificado — nenhuma alteração necessária ou alterações aplicadas>
generator_scripts: <verificado — nenhuma alteração necessária ou alterações aplicadas>
test_results:
tests_run: <número>
tests_passed: <número>
tests_failed: <número>
test_command: <comando usado>
failures_analysis:
pre_existing: <lista ou nenhum>
caused_by_patch: <lista ou nenhum>
test_bug: <lista ou nenhum>
fallback_attempts:
- hypothesis: <rótulo da hipótese>
reason_abandoned: <por que falhou>
rollback_performed: <sim / não>
verdict: <PATCH APROVADO / PATCH FALHOU — HIPÓTESES ESGOTADAS>
Se o patch foi bem-sucedido, o veredito é PATCH APROVADO. Se todas as hipóteses foram tentadas e nenhuma passou nos testes, o veredito é PATCH FALHOU — HIPÓTESES ESGOTADAS.
Integração com Outras Habilidades
- hdl-fault-localization (https://github.com/AgainstWar/hdl-fault-localization) — O skill irmão que faz a localização de falhas. Use junto para um pipeline completo de localização → reparo.
Palavras-chave para Acionamento de Agente
HDL, minimal repair, patch planning, side-effect scanner, artifact link checker,
hardware contract verification, RTL bug fix, regression testing, fallback hypothesis