Communitygithub.com

truepath

Gere uma simulação HTML autocontida que explica um processo ou caminho de bug passo a passo — um ponto viaja pelo caminho real, um painel de dados mostra o que muda em cada etapa e cenários "antes / depois" são reproduzidos lado a lado com sua primeira divergência marcada.

O que é truepath?

Truepath é uma skill para agentes de IA (como Claude Code, Cursor ou Codex) que cria simulações visuais interativas de processos, regras de decisão ou bugs. A partir de um arquivo `spec.json` descrevendo nós, arestas e cenários, o script `build.py` gera um único arquivo HTML offline que anima o percurso de um ponto pelo grafo, exibindo em um painel os valores que mudam a cada etapa. A skill suporta cenários de "antes/depois" lado a lado com a primeira divergência destacada, comparação de múltiplas regras (grid), e obtém vereditos de um oracle executado em um snapshot congelado do repositório ou de um port JavaScript declarado. Treze verificações (C1 a C13) garantem que a simulação nunca contradiga a lógica real do código. É ideal para responder a pedidos como "mostre o processo em execução", "anime este bug", "compare antes e depois da correção", ou para explicar regras de decisão com casos reais ou ilustrativos. Funciona offline, com tema claro/escuro automático, e é extensível via oracles em qualquer linguagem (testes, scripts, JUnit).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bastien-gallay/truepath/tree/HEAD/skills/truepath

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que truepath faz?

Um spec.json descreve o processo (nós, arestas), os cenários (caminho, mensagens, legendas, entradas) e de onde vêm os vereditos. build.py calcula os vereditos, organiza o grafo, executa as verificações e gera um .html offline — ou nada.

spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html   (ou nada)
layout.py ──┘                                └► fixture.json (--export)

Fluxo de trabalho

  1. Copie o exemplo mais próximo junto às anotações do assunto (veja Arquivos), renomeie spec.json para <assunto>.spec.json.

  2. Descreva nós e arestas. Cada nó sumidouro (um resultado) recebe um kind; kinds são as únicas cores, cada um com um rótulo na legenda.

  3. Escolha de onde vêm os vereditos (veja abaixo): um oracle quando a regra existe no código, um port JS caso contrário.

  4. Escreva os cenários. Cada um declara sua origin, seus inputs, os campos expectados, e seus steps ao longo de arestas reais.

  5. Construa, depois abra o arquivo:

    python3 <dir-da-skill>/scripts/build.py <assunto>.spec.json
    
  6. Leia as violações, corrija o spec — nunca a verificação.

spec.json constrói sim.html, <assunto>.spec.json constrói <assunto>.sim.html; -o nomeia outro arquivo.

A página abre na primeira aba com o painel de detalhes aberto. Recolher o painel muda para a visão geral: todo o caminho desenhado, um ponto percorrendo-o em loop.

De onde vêm os vereditos

FonteChave do specUse quandoMarcado no painel
Oracleoraclea regra existe em um repositório✓ código
Portport: "decide.js"ainda sem código, regra em discussão, processo sem código⚠ portado

Protocolo do Oracle. build.py obtém git archive de oracle.ref (nunca o checkout ativo: um branch em desenvolvimento pode mudar durante a construção), extrai oracle.paths, vincula oracle.link (tipicamente node_modules) e copia oracle.files para dentro dele, depois executa oracle.cmd em oracle.cwd com:

  • TRUEPATH_ORACLE_IN: um array JSON de todos os inputs de cada cenário;
  • TRUEPATH_ORACLE_OUT: onde escrever um array JSON de vereditos, mesma ordem.

oracle.repo é lido a partir da pasta do spec quando é relativo. link e files são escritos como {caminho no snapshot: de onde vem}: um caminho no repositório para link, um arquivo ao lado do spec para files.

Um veredito é um objeto de campos. outcome é obrigatório: nomeia o nó onde o caminho deve terminar, e é o que vincula um cenário à lógica. basis opcionalmente diz, por campo, se o código real o computou ("código: …"), a cola copiou um comportamento ("port: …"), ou a simulação o define (qualquer outro texto, mostrado ◇ definição). A página mostra essa marca ao lado de cada valor do painel cujo campo tem uma base, seu texto completo ao passar o mouse, e --export afirma apenas campos cuja base é código: um campo sem base conta como código sob um oracle, como portado sob um port. Um oracle pode misturá-los: uma regra ainda em discussão é portada ao lado das regras que o código já executa. Qualquer runner funciona: um arquivo de teste do próprio framework do projeto, um script, um teste JUnit para Java. O rodapé nomeia a ref e o sha curto que produziram os vereditos.

Um oracle que é um arquivo de teste pode funcionar como suíte de regressão: quando TRUEPATH_ORACLE_IN está definido, ele escreve os vereditos; caso contrário, lê o fixture exportado e o afirma. Os cenários então vivem uma vez, no spec, e rodam em CI. examples/loyalty-tier/src/oracle.js faz ambos.

Referência do spec

ChaveFormaNotas
title, subtitle, sourcestringssource vai para o rodapé; como todo texto do spec, são exibidos como texto, nunca lidos como HTML
langen (padrão) ou fridioma das palavras da própria página; o texto do spec é escrito nesse idioma
kinds{id: {label, color}}no máximo 4
nodes[{id, label, role?, kind?}]role: "decision" marca um ponto de ramificação; onde um caminho começa é encontrado e desenhado redondo; sumidouros precisam de kind
edges[[from, to, label]]label "" para nenhuma
panel[{label, value, at, labels?, digits?, compared?}]value lê inputs.x ou verdict.y; mostrado a partir do passo at (0 é o primeiro); labels mapeia um valor para o que a página mostra ("true", "false", "null", "[]" para esses valores); digits preenche com zeros um código numérico até esse comprimento; compared: true para a linha que nomeia o que um par compara (a correção, a regra), deixado de fora da busca pela primeira divergência
scenarios[{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}]origin: {kind: real|illustrative, text}; steps: [{hop: [from, to], message, caption}]; undecided: true marca uma regra ainda não decidida; caseName nomeia o caso em um fixture exportado
pairs[{before, after, tab, summary}]dois ids de cenários, reproduzidos lado a lado como − e +; mesmo número de passos
grid{baseline, questions | variants, cases, steps, expect?, show?, hover, summary?}casos × respostas (ou regras, correções), em vez de scenarios e pairs: veja abaixo
oracle{repo, ref, paths, link?, files?, cwd, cmd}veja acima
portcaminho para um arquivo CommonJS exportando decide(inputs)usado quando não há oracle
export{dir, fixture, assert}--export <worktree> escreve o fixture lá

Comparando várias regras: a grid

Quando a pergunta é "o que cada resposta possível faz para cada caso", declare uma grid. Prefira questions a uma lista plana de regras: o leitor decide pergunta por pergunta, então a página deve ser organizada assim.

  • baseline: {id, label, short?, inputs}, o que acontece hoje;
  • questions: [{id, text, options: [{id, label, inputs}], cases, if?}]. cases lista os casos nos quais essa pergunta é decidida; if: {"Q1": "1A"} pede apenas após essa resposta. build.py deriva uma variante por conjunto coerente de respostas (1A+2A, 1A+2B, 1B), mesclando os inputs das opções;
  • cases: [{id, label, summary, origin, inputs, steps?}]; label nomeia a linha em palavras que o leitor conhece, não um código de caso;
  • steps: compartilhados por todas as células, a menos que um caso traga os seus próprios;
  • expect: {case: {variant: {field: value}}}, verificado por C3;
  • show: a única linha do painel que uma célula da matriz mostra (por padrão, a primeira de hover); hover: as linhas que uma célula mostra ao passar o mouse;
  • summary: uma linha acima da matriz.

Uma variants: [{id, label, short?, note?, inputs}] plana com baseline como um id ainda funciona: a matriz então tem uma seção, cada caso contra cada variante.

A página abre na matriz: uma tabela por pergunta, seus casos contra o hoje e cada resposta, a linha da célula marcada ≠ onde difere do hoje. Não há aba por caso: um clique em uma célula a abre, o hoje ao lado dessa resposta, com a primeira divergência marcada. Dois botões, − e +, escolhem um lado entre as respostas da seção (1A ao lado de 1B, não apenas ao lado do hoje), cada um nomeado como sua pergunta o nomeia; ← matriz volta. No painel, uma linha com "value": "answer" e "compared": true nomeia a resposta reproduzida.

Modelos de passos. message, caption e hop podem citar {inputs.x} ou {verdict.y}: são preenchidos após a lógica ser executada, formatados como a linha do painel que lê o mesmo caminho. Um hop para {verdict.outcome} permite que uma única lista de passos sirva para todas as regras.

Verificações

IdRecusa
C1um passo cujo hop não é uma aresta
C2um caminho que quebra, não começa em um nó fonte, ou não tem passo
C3um campo expect que a lógica contradiz
C4um caminho que termina em outro lugar que não o outcome da lógica, ou uma lógica que não dá nenhum
C5um resultado sem um kind, um kind sem legenda, mais de 4 kinds
C6um rótulo mais largo que sua caixa (13px monoespaçada)
C7um cenário sem uma origin dizendo real ou ilustrativo, e de onde
C8um par cujos cenários não podem avançar juntos, ou são desconhecidos
C9uma linha do painel que lê um campo que falta em um cenário
C10uma célula da matriz nomeando uma linha do painel que não existe
C11um caso mostrado sob uma pergunta cuja célula ainda depende de outra pergunta
C12um caso em nenhuma seção da matriz, ou uma seção nomeando um caso desconhecido
C13uma linha do painel configurada para aparecer em um passo que o cenário não tem

C3 e C4 são o ponto: um cenário que diz algo que o código não faz não pode ser publicado. C6 protege o layout em vez do spec: as caixas são dimensionadas para seus rótulos, então ele dispara apenas se layout.py parar de fazer isso. Prove que uma nova verificação morde quebrando sua entrada uma vez, em tests/. Cada verificação é uma função em build.py, listada em CHECKS sob o id desta tabela.

Um spec que a construção não consegue ler (uma chave faltando, uma aresta para um nó desconhecido, um port que lança exceção) é recusado da mesma forma, em palavras claras, antes que as verificações sejam executadas.

Regras de design

  • Um elemento móvel por diagrama: um único ponto, velocidade constante, um hop de cada vez. Dois diagramas lado a lado se movem em sincronia.
  • Arestas percorridas são sólidas, não percorridas são tracejadas e cinzas; nós fora do caminho desaparecem.
  • A cor codifica apenas o tipo do resultado. Em um par, a primeira divergência (o primeiro passo onde um valor do painel difere) é contornada em âmbar e marcada ≠ em ambos os lados, e o painel mostra colunas − / +.
  • Cenários ilustrativos apenas onde nenhum caso real atinge aquele resultado; diga de onde vem o caso real (ticket, registro, medida, data).
  • Uma grid mostra um campo por célula; três campos por célula tornaram a matriz ilegível.
  • Tema claro por padrão, escuro sob prefers-color-scheme; sem fonte web, para que o arquivo funcione offline.

Arquivos

CaminhoFunção
scripts/build.pylê o spec, obtém os vereditos, executa as verificações, escreve a página e o export
scripts/runtime.htmla página; build.py lhe dá o que ela mostra, já formatado, e nada mais do spec
scripts/layout.pylayout em camadas: caixas dimensionadas para seus rótulos, arestas ortogonais
examples/refund-window/um port JS e um par antes/depois
examples/free-shipping/uma grid: duas perguntas abertas, cada uma decidida nos casos que muda
examples/loyalty-tier/um oracle no próprio src/ da pasta, sua cola e o fixture que --export escreve

Arquivos gerados (.truepath/, onde vivem os snapshots de um oracle, e *.html ao lado de um spec) são saída da construção. Os exemplos de port mantêm seus sim.html para que a skill possa ser vista sem executá-la. loyalty-tier não mantém nenhum: seu rodapé nomeia o commit que produziu os vereditos, então a página muda a cada commit, e ela é construída apenas dentro de um repositório git que a contém.

Limites

  • Um tipo de diagrama: o fluxo do processo. Visualizações de sequência e arquitetura não são construídas.
  • C6 é medida no macOS (ui-monospace); uma fonte Windows mais estreita apenas adiciona espaço.
  • Os passos são declarados, não derivados da lógica: C3 e C4 pegam um resultado errado, não uma mensagem intermediária errada.

Habilidades Relacionadas