Documentação Markdown no Diagrama (kikwi:documentation)

Pense na diferença entre a planta de uma casa e o memorial descritivo. A planta é o que o construtor segue: paredes, medidas, o essencial para executar. O memorial explica por que a parede da sala é estrutural, que tipo de fiação passa ali, o histórico daquela reforma. Os dois documentos servem propósitos diferentes — e ninguém entope a planta de parágrafos, porque isso a tornaria ilegível justamente para quem precisa construir. Onde a analogia quebra: a planta e o memorial são arquivos separados; no Kikwiflow, o kikwi:documentation mora dentro do mesmo .kikwi — e é por isso que a recomendação de uso é restrita.

Cada nó de um .kikwi aceita um campo opcional kikwi:documentation: um texto Markdown associado àquele nó — trechos de código, tabelas, diagramas Mermaid, links. É lido e renderizado pelas ferramentas visuais (Craft, extensão do VS Code), no painel de configuração do nó.

{
  "id": "EXECUTAR_BACKGROUND_CHECK",
  "name": "Executar Background Check",
  "type": "EXECUTABLE_TASK",
  "executor": "backgroundCheckTaskHandler",
  "kikwi:documentation": "Consulta o birô de crédito e classifica o risco em `BAIXO`/`MEDIO`/`ALTO`.\n\n- Lança `ProcessErrorException(\"CADASTRO_INCOMPLETO\")` quando faltam dados obrigatórios.\n- Escreve a variável `resultadoExecucao`.\n\nVer regra de negócio RN-042.",
  "outgoing": [ { "targetNodeId": "GATEWAY_RISCO" } ]
}

Para que serve

• Onboarding de quem chega ao processo depois. A pessoa abre o diagrama e, clicando num nó, lê o que aquele passo faz, quais variáveis toca, que regra de negócio o governa — sem caçar a classe Java correspondente.
• Revisão de arquitetura. Um .kikwi anotado é um artefato de discussão: o time revisa o fluxo e as anotações juntos, num só lugar.
• Documentar um serviço Java existente como diagrama. A skill document-java-as-kikwi lê um projeto Java e produz um .kikwi somente-documentação — cada nó com kikwi:documentation rico (trechos reais de código, Mermaid para ramificações internas). Esse .kikwi nunca é implantado: ele existe para ser lido, não executado.

Quando usar / quando não usar

Situação	Recomendação
.kikwi gerado a partir de código para entender/documentar um fluxo (via document-java-as-kikwi)	Use — é exatamente o propósito. Esse arquivo não vai para o motor.
Anotar um nó com uma frase curta (o que faz, que variável escreve, link para a regra) num processo que vai rodar	Use com moderação — mantenha curto.
Enterrar parágrafos longos, histórico de decisões, ou documentação extensa dentro de um .kikwi que roda em produção	Não faça.
Processo de missão crítica	Não use kikwi:documentation como repositório de documentação. Mantenha a definição enxuta; a documentação densa vive fora dela (wiki, ADRs, este guia).

Por que a restrição

Um .kikwi que roda em produção é código: versionado, revisado em pull request, comparado num diff, e carregado inteiro na memória do motor a cada deploy. Encher esse arquivo de prosa:

• Polui o diff. Uma mudança de uma linha na lógica do fluxo fica escondida no meio de blocos de texto — quem revisa perde o sinal.
• Mistura duas responsabilidades — executar e explicar — num artefato que precisa ser confiável para a primeira.
• Desatualiza silenciosamente. Diferente do código, ninguém compila a prosa: ela apodrece dentro da definição sem nenhum sinal.

Uma frase objetiva por nó ("classifica o risco; escreve resultadoExecucao; ver RN-042") é útil e barata. Um ensaio, não.

Próximo passo

Você chegou ao fim dos capítulos de tipos de nó. Para ver o processo completo montado, volte ao tutorial de abertura de conta; para os detalhes das ferramentas de modelagem, veja o Craft e a extensão do VS Code.