Como Criar e Validar Chains

Guia prático para modelar relações causais estruturadas

1 Como Criar e Validar Chains

Este guia mostra como construir chains (cadeias causais) para expressar relações entre conceitos de forma sistemática e auditável.

Você deve usar este guia se:

Precisa expressar relações de causalidade, influência ou mediação
Quer construir mapas de relações entre códigos
Precisa validar a consistência lógica de suas chains
Quer extrair redes de relações para análise ou visualização

1.1 O que é uma Chain?

Uma chain (cadeia) é uma sequência de códigos conectados por relações, expressando como conceitos se influenciam mutuamente.

1.1.1 Sintaxe Básica

chain: conceito_a -> RELACAO -> conceito_b

Exemplo:

chain: custo_alto -> INIBE -> adocao

Lê-se: “custo_alto INIBE adocao”

1.2 Como Criar Chains Simples

1.2.1 Chain de Dois Elementos

A forma mais básica: um código influencia outro diretamente.

ITEM @entrevista_01
    quote: "O preço elevado desestimula a compra"
    memo: Barreira econômica identificada
    chain: preco_elevado -> INIBE -> decisao_de_compra
END ITEM

Quando usar: Para relações diretas e não mediadas.

1.2.2 Chains com Múltiplas Relações

Para expressar cadeias causais complexas:

chain: falta_de_treinamento -> CAUSA -> baixa_competencia -> INIBE -> adocao

Lê-se: “Falta de Treinamento CAUSA Baixa Competência, que INIBE Adoção”

Quando usar: Para capturar mecanismos causais com elementos intermediários.

1.3 Como Escolher Relações Apropriadas

As relações devem estar declaradas no template do projeto (campo chain). Tipos comuns:

Relação	Significado	Exemplo
`CAUSA`	X é causa direta de Y	`erro_de_software -> CAUSA -> falha_do_sistema`
`INIBE`	X reduz ou impede Y	`custo_alto -> INIBE -> adocao`
`FAVORECE`	X promove ou facilita Y	`treinamento -> FAVORECE -> usabilidade`
`MEDIA`	X é intermediário entre A e Y	`suporte_tecnico -> MEDIA -> satisfacao`
`CORRELACIONA`	X e Y ocorrem juntos (sem direção)	`alta_rotatividade -> CORRELACIONA -> baixo_engajamento`

Declare relações no template do projeto:

FIELD chain TYPE CHAIN
    SCOPE ITEM
    DESCRIPTION Cadeia causal entre conceitos
    RELATIONS
        CAUSA: X é causa direta e necessária de Y
        INIBE: X reduz probabilidade ou intensidade de Y
        FAVORECE: X promove ou facilita Y
        MEDIA: X é elemento intermediário entre A e Y
        CORRELACIONA: X e Y ocorrem juntos, sem direção causal definida
    END RELATIONS
END FIELD

1.4 Como Construir Chains Complexas

1.4.1 Chains Divergentes (Um Causa Vários)

# Chain 1
chain: falta_de_recursos -> INIBE -> investimento_em_ia

# Chain 2
chain: falta_de_recursos -> INIBE -> treinamento_de_equipe

# Chain 3
chain: falta_de_recursos -> CAUSA -> priorizacao_de_curto_prazo

Quando usar: Para identificar causas de múltiplos efeitos.

1.4.2 Chains Convergentes (Vários Causam Um)

# Chain 1
chain: facilidade_de_uso -> FAVORECE -> satisfacao

# Chain 2
chain: suporte_responsivo -> FAVORECE -> satisfacao

# Chain 3
chain: custo_acessivel -> FAVORECE -> satisfacao

Quando usar: Para identificar fatores múltiplos contribuindo para mesmo resultado.

1.4.3 Chains com Mediadores

Quando há elementos intermediários:

chain: investimento_em_capacitacao -> FAVORECE -> competencia_da_equipe -> FAVORECE -> qualidade_do_output

Quando usar: Para explicar “o porquê” de uma relação (mecanismo causal).

1.5 Como Validar Chains

1.5.1 Validação Automática pelo Compilador

Ao compilar, o Synesis valida automaticamente:

✅ Todos os códigos existem na ontologia
✅ Todas as relações existem na ontologia
✅ Estrutura sintática está correta

synesis check analysis.synp

Erros comuns:

Erro	Causa	Solução
`Code 'X' not found in ontology`	Código não definido	Adicione o código em `.syno`
`Relation 'Y' not found`	Relação não definida	Adicione a relação em `.syno`
`Invalid chain syntax`	Estrutura malformada	Verifique formato: `A -> REL -> B`
`Chain must have odd number of elements`	Faltou código ou relação	Chains têm formato: `C -> R -> C -> R -> C`

1.5.2 Validação Semântica Manual

Perguntas para revisar suas chains:

Direcionalidade: A ordem A → B faz sentido? Ou deveria ser B → A?
Tipo de relação: “INIBE” é a relação correta, ou deveria ser “CAUSA”?
Completude: Faltam elementos intermediários importantes?
Evidência: A citação realmente suporta esta chain?

1.6 Como Extrair e Analisar Chains

Após compilar, as chains ficam disponíveis em:

1.6.1 CSV

output/chains.csv:

source,item_id,chain_type,elements
entrevista_01,1,qualified,"Custo Alto,INIBE,Adoção"
entrevista_02,3,qualified,"Treinamento,FAVORECE,Competência,FAVORECE,Qualidade"

Use para: Análise quantitativa (contagem, frequência de relações).

1.6.2 JSON

output/analysis.json:

{
  "chains": [
    {
      "codes": ["Custo Alto", "Adoção"],
      "relations": ["INIBE"],
      "source": "@entrevista_01",
      "quote": "..."
    }
  ]
}

Use para: Integração com ferramentas de visualização ou Neo4j.

1.7 Como Visualizar Chains

1.7.1 Grafos no Synesis Explorer (VSCode)

Abra projeto no VSCode com extensão Synesis Explorer instalada
Pressione Ctrl+Alt+G (Show Relation Graph)
Visualize grafo interativo Mermaid.js

1.7.2 Exportar para Neo4j

Para análises avançadas de rede:

python synesis2graph.py --project analysis.synp --config neo4j.toml

Consulte Como exportar para Neo4j para detalhes.

1.8 Padrões Comuns de Chains

1.8.1 Padrão “Barreira-Inibição”

chain: barreira_x -> INIBE -> comportamento_desejado

Exemplo:

chain: falta_de_informacao -> INIBE -> confianca -> INIBE -> adocao

1.8.2 Padrão “Facilitador-Promoção”

chain: facilitador_x -> FAVORECE -> comportamento_desejado

Exemplo:

chain: demonstracao_pratica -> FAVORECE -> compreensao -> FAVORECE -> adocao

1.8.3 Padrão “Feedback Loop”

Expresse ciclos usando múltiplas chains:

# Chain 1: Ida
chain: alta_satisfacao -> FAVORECE -> engajamento

# Chain 2: Volta
chain: alto_engajamento -> FAVORECE -> satisfacao

Nota: Chains individuais não podem ter ciclos diretos (A → B → A). Use chains separadas.

1.8.4 Padrão “Trade-off”

# Chain 1
chain: automacao_completa -> FAVORECE -> eficiencia

# Chain 2
chain: automacao_completa -> INIBE -> flexibilidade

Quando usar: Para expressar dilemas ou tensões entre objetivos.

1.9 Como Iterar Sobre Chains

1.9.1 Passo 1: Rascunho Inicial

Na primeira leitura, crie chains exploratórias:

ITEM @doc_01
    quote: "A tecnologia ajuda, mas é cara"
    chain: tecnologia -> FAVORECE -> eficiencia
    chain: custo -> INIBE -> adocao
END ITEM

1.9.2 Passo 2: Refinamento

Após revisar várias fontes, consolide padrões recorrentes:

# Versão refinada
chain: utilidade_percebida -> FAVORECE -> intencao_de_uso
chain: custo_percebido -> INIBE -> intencao_de_uso
chain: intencao_de_uso -> FAVORECE -> comportamento_de_adocao

1.9.3 Passo 3: Validação Cruzada

Compare chains extraídas de fontes diferentes:

# Fonte A
chain: treinamento -> FAVORECE -> competencia -> FAVORECE -> adocao

# Fonte B
chain: mentoria -> FAVORECE -> competencia -> FAVORECE -> adocao

# Insight: "competencia" é mediador recorrente

1.10 Como Documentar Decisões sobre Chains

Adicione notas explicativas:

ITEM @policy_doc
    quote: "Investimento em infraestrutura digital reduziu custos operacionais"

    memo: Relação causal direta confirmada por dados quantitativos (Tabela 3)

    chain: infraestrutura_digital -> INIBE -> custos_operacionais

    # DECISÃO 2026-02-04: Escolhemos INIBE em vez de CAUSA para
    # refletir natureza gradual (não binária) do efeito
END ITEM

1.11 Quando NÃO Usar Chains

Chains não são apropriadas para:

Descrições simples: Use code em vez de forçar uma chain

# ❌ Forçado
chain: Custo -> DESCREVE -> Entrevista

# ✅ Apropriado
code: Custo

Relações ambíguas: Se você não tem certeza da direção ou tipo, deixe como código isolado e anote sua incerteza no campo MEMO.
Taxonomias: Use TOPIC na ontologia em vez de chains hierárquicas.

1.12 Exercício Prático

1.12.1 Cenário

Você tem esta citação:

“A falta de suporte técnico adequado gerou frustração na equipe, o que levou à baixa adesão ao novo sistema.”

1.12.2 Tarefa

Construa uma chain que capture esta relação causal.

1.12.3 Solução Proposta

ITEM @entrevista_gerente
    quote: "A falta de suporte técnico adequado gerou frustração na equipe, o que levou à baixa adesão ao novo sistema."

    memo: Cadeia causal clara: suporte insuficiente -> frustração -> baixa adoção

    code: suporte_tecnico_inadequado
    code: frustracao
    code: baixa_adesao

    chain: suporte_tecnico_inadequado -> CAUSA -> frustracao -> INIBE -> adesao_ao_sistema
END ITEM

Validação: - ✅ Três códigos, duas relações (estrutura válida) - ✅ Relações CAUSA e INIBE declaradas no template - ✅ Cadeia reflete sequência temporal da citação - ✅ Campo memo explicita interpretação

1.13 Referências

Para informações complementares:

Referência da Linguagem — Sintaxe formal de chains
Como definir uma ontologia — Criar relações reutilizáveis
Tutorial Getting Started — Exemplos básicos de chains

Ficou com dúvidas? Consulte GitHub Discussions ou abra uma issue específica.