Passei por uma situação parecida em um projeto meu, e talvez a abordagem que usei possa te dar algumas ideias :)
No meu caso, já havia documentação, mas o desafio era manter as regras de negócio consistentes entre vários documentos e a implementação. Uma mudança podia afetar a especificação funcional, a API, as regras de negócio e a descrição da interface ao mesmo tempo.
Acabei construindo um fluxo com apoio de IA para identificar os trechos afetados, propor alterações e revisar a consistência entre os documentos. A parte de aplicação e validação ficou com scripts, mantendo o vínculo entre a decisão, a justificativa e o que foi alterado. As mudanças são aplicadas primeiro em cópias, com aprovação antes de atualizar a documentação oficial.
Uma coisa que considero bem importante nesse processo: o código mostra como o sistema se comporta hoje, mas isso nem sempre significa que aquele comportamento é a regra desejada. Por isso, quando aparece uma divergência, a IA pode apontar e sugerir uma correção, mas a definição da regra precisa ter respaldo de quem conhece o negócio. Senão, corremos o risco de documentar um bug e transformá-lo em “comportamento oficial” 😅
Para o teu cenário, eu pensaria em aproveitar esse snapshot que já fizeste e criar uma base central versionada, independente dos repositórios dos microserviços. Cada regra poderia ter um identificador, uma descrição, exemplos, exceções conhecidas e referências aos serviços envolvidos. Não precisaria começar com uma ferramenta sofisticada; um repositório dedicado à documentação poderia ser um primeiro passo.
A ideia das Actions parece um bom ponto de entrada. Eu só ampliaria um pouco o papel delas: além de recolher o comentário do PR, poderiam analisar o diff junto com as regras relacionadas e gerar uma proposta de atualização nessa base central. Algo que deixasse claro: “esta mudança parece alterar a regra X, deste comportamento para aquele, por este motivo”. Quem revisa teria algo concreto para confirmar ou corrigir.
Também tentaria separar “mudança aprovada” de “mudança em produção”, vinculando a atualização ao registro de deploy ou release. Isso ajudaria a responder depois qual comportamento estava disponível em determinado momento.
Sobre o “antes conseguia fazer X”, eu começaria a transformar esses relatos em exemplos concretos ligados às regras: em quais condições o cliente conseguia, qual era o resultado e se aquilo deve continuar sendo permitido. Esses exemplos poderiam alimentar testes de caracterização do legado e testes de aceitação durante a migração. A documentação ajudaria a preservar o motivo da regra; os testes, a verificar o comportamento esperado.
Ainda não tenho essa integração automática entre PRs de vários microserviços pronta — o que construí foi o fluxo de atualização documental com revisão e rastreabilidade. Mas eu começaria a adaptação por um serviço e algumas regras críticas, para ajustar o processo antes de expandir.
Acho que o snapshot que já fizeste é um ótimo começo. Minha sugestão seria usar a IA para reduzir o trabalho de encontrar impactos e preparar as alterações, mantendo a decisão sobre mudanças de negócio explícita e fácil de consultar depois. Espero que a experiência ajude! :)