Communitygithub.com

truepath

プロセスやバグのパスをステップバイステップで説明する、自己完結型のHTMLシミュレーションを生成します。1つのドットが実際のパスをたどり、データパネルが各ステップでの変化を表示し、「before/after」シナリオを並べて、最初の相違点をマークします。判定はリポジトリ自身のコード(凍結されたgitスナップショット上で実行されるオラクル)または宣言されたJSポートによって計算され、それらに矛盾する出力は拒否されます。

truepath とは?

truepathは、プロセスフローのシミュレーションを生成するためのスキルです。spec.json という1つの設定ファイルに、プロセス(ノードとエッジ)、シナリオ(パス、メッセージ、キャプション、入力)、そして判定のソースを記述します。build.py スクリプトが判定を計算し、グラフをレイアウトし、チェックを実行して、オフラインで表示可能な単一のHTMLファイルを生成します。このスキルは、コードベースに存在するルール(オラクル)と、まだコード化されていないルール(JSポート)の両方をサポートし、シナリオに記述された期待値と実際のコードの動作が一致することを厳密に検証します。特に、バグの原因を視覚的に追跡したり、修正前後の動作を比較したり、複雑な決定ルールを説明するのに役立ちます。主なプラットフォームはClaude Codeで、開発者がプロセスのデバッグやドキュメント化を効率的に行えるように設計されています。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

truepath は何をしますか?

1つの spec.json がプロセス(ノード、エッジ)、シナリオ(パス、メッセージ、キャプション、入力)、および判定のソースを記述します。build.py が判定を計算し、グラフをレイアウトし、チェックを実行し、1つのオフライン .html ファイルを書き出します。チェックに失敗した場合は何も書き出しません。

spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html   (または何も出力しない)
layout.py ──┘                                └► fixture.json (--export)

ワークフロー

  1. 対象のメモの隣にある最も近い例をコピーします(ファイル を参照)。spec.json を <subject>.spec.json にリネームします。

  2. ノードとエッジを記述します。すべてのシンクノード(結果)には kind を指定します。kind が唯一の色であり、それぞれに凡例のラベルが付きます。

  3. 判定のソースを選択します(下記参照):コード内にルールが存在する場合は oracle、それ以外の場合は JS の port を使用します。

  4. シナリオを記述します。各シナリオは、origin、inputs、期待される判定フィールド expect、および実際のエッジに沿った steps を宣言します。

  5. ビルドして、ファイルを開きます:

    python3 <skill-dir>/scripts/build.py <subject>.spec.json
    
  6. 違反を読み、spec を修正します — チェック自体は修正しません。

spec.json は sim.html をビルドし、<subject>.spec.json は <subject>.sim.html をビルドします。-o オプションで別のファイル名を指定できます。

ページは最初のタブが開き、詳細パネルが表示された状態で開きます。パネルを折りたたむと概要表示に切り替わります:パス全体が描画され、1つのドットがその上をループします。

判定のソース

ソースSpec キー使用するタイミングパネル内の表示
Oracleoracleリポジトリ内にルールが存在する場合✓ code
Portport: "decide.js"コードがない場合、議論中のルール、コード化されていないプロセス⚠ ported

Oracle プロトコル。 build.py は、oracle.ref の git archive を取得し(ライブチェックアウトは使用しません:作業中のブランチはビルド中に移動する可能性があります)、oracle.paths を抽出し、oracle.link(通常は node_modules)をリンクして、oracle.files をその中にコピーし、oracle.cwd で oracle.cmd を以下の環境変数と共に実行します:

  • TRUEPATH_ORACLE_IN: すべてのシナリオの inputs の JSON 配列。
  • TRUEPATH_ORACLE_OUT: 判定の JSON 配列を同じ順序で書き込むファイルパス。

oracle.repo は、相対パスで指定された場合、spec ファイルのフォルダから読み取られます。link と files はどちらも {スナップショット内のパス: 元の場所} として書き込まれます:link はリポジトリ内のパス、files は spec の隣にあるファイルです。

判定はフィールドのオブジェクトです。outcome は必須で、パスが終了するノードを指定し、シナリオをロジックに結び付けます。basis はオプションで、フィールドごとに、実際のコードが計算したか("code: …")、glue が振る舞いをコピーしたか("port: …")、またはシミュレーションが定義したか(その他のテキスト、◇ definition と表示)を示します。ページは、基準を持つすべてのパネル値の横にそのマークを表示し、ホバーで全文を表示します。--export は、基準が code であるフィールドのみをアサートします:Oracle の下で基準のないフィールドは code と見なされ、port の下では ported と見なされます。1つの Oracle でこれらを混在させることができます:まだ議論中のルールは、コードが既に実行しているルールの横に ported として表示されます。任意のランナーを使用できます:プロジェクト独自のフレームワークのテストファイル、スクリプト、Java の JUnit テストなど。フッターには、判定を生成した ref と短い SHA が表示されます。

テストファイル Oracle は回帰テストスイートとしても機能します:TRUEPATH_ORACLE_IN が設定されている場合は判定を書き込み、設定されていない場合はエクスポートされた fixture を読み込んでアサートします。シナリオは spec 内に一度だけ存在し、CI で実行されます。examples/loyalty-tier/src/oracle.js は両方の動作を実行します。

Spec リファレンス

キー形状備考
title, subtitle, source文字列source はフッターに表示されます。spec のすべてのテキストと同様に、HTML として読み取られることはなく、テキストとして表示されます。
langen (デフォルト) または frページ自身の単語の言語。spec のテキストはその言語で記述されます。
kinds{id: {label, color}}最大4つまで
nodes[{id, label, role?, kind?}]role: "decision" は分岐点を示します。パスが開始する場所は検出され、丸く描画されます。シンクには kind が必要です。
edges[[from, to, label]]ラベルがない場合は ""
panel[{label, value, at, labels?, digits?, compared?}]value は inputs.x または verdict.y を読み取ります。ステップ at(0 が最初)から表示されます。labels は値("true", "false", "null", "[]" など)をページに表示するものにマッピングします。digits は数値コードを指定された長さにゼロパディングします。compared: true は、ペアが比較するもの(修正、ルール)を指定する行に使用され、最初の相違点検索から除外されます。
scenarios[{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}]origin: `{kind: real
pairs[{before, after, tab, summary}]2つのシナリオ ID。− と + として並べて再生されます。同じステップ数が必要です。
grid`{baseline, questionsvariants, cases, steps, expect?, show?, hover, summary?}`
oracle{repo, ref, paths, link?, files?, cwd, cmd}上記参照
portCommonJS ファイルへのパス。decide(inputs) をエクスポートします。Oracle がない場合に使用します。
export{dir, fixture, assert}--export <worktree> で fixture をそこに書き込みます。

複数のルールの比較:グリッド

「それぞれの可能な回答が各ケースに何をもたらすか」という質問がある場合、grid を宣言します。ルールのフラットなリストよりも questions を優先します:読み手は質問ごとに決定するため、ページはそれに応じてレイアウトされるべきです。

  • baseline: {id, label, short?, inputs}、現在の状態。
  • questions: [{id, text, options: [{id, label, inputs}], cases, if?}]。 cases はその質問が決定するケースをリストします。if: {"Q1": "1A"} は、その回答があった場合にのみ質問を行います。build.py は、一貫性のある回答セット(1A+2A、1A+2B、1B)ごとに1つのバリアントを派生させ、オプションの inputs をマージします。
  • cases: [{id, label, summary, origin, inputs, steps?}];label は読み手が知っている単語で行に名前を付けます(ケースコードではありません)。
  • steps: ケースが独自のものを持たない限り、すべてのセルで共有されます。
  • expect: {case: {variant: {field: value}}}、C3 によってチェックされます。
  • show: マトリックスセルが表示する1つのパネル行(デフォルトは hover の最初の行)。hover: セルがホバー時に表示する行。
  • summary: マトリックスの上の行。

フラットな variants: [{id, label, short?, note?, inputs}] と baseline を ID として使用することもできます。その場合、マトリックスは1つのセクションを持ち、すべてのケースがすべてのバリアントと比較されます。

ページはマトリックスで開きます:質問ごとに1つのテーブル。各テーブルには、そのケースが今日の状態と各回答に対して表示され、セルの線が今日の状態と異なる場合は ≠ でマークされます。ケースごとのタブはありません。セルをクリックすると開き、今日の状態とその回答が並んで、最初の相違点がマークされます。2つのボタン行 − と + は、セクションの回答の中からどちらかの側(今日の状態とだけでなく、1A と 1B など)を選択し、それぞれ質問の名前で名前が付けられます。← matrix で戻ります。パネルでは、"value": "answer" と "compared": true を持つ行が、再生される回答に名前を付けます。

ステップテンプレート。 message、caption、hop は {inputs.x} または {verdict.y} を引用できます。これらはロジックの実行後に、パネル行が同じパスを読み取るのと同じようにフォーマットされて埋められます。{verdict.outcome} へのホップにより、1つのステップリストがすべてのルールに使用できるようになります。

チェック

ID拒否する条件
C1ステップのホップがエッジではない場合
C2パスが壊れている、ソースノードから始まっていない、またはステップがない場合
C3ロジックが expect フィールドと矛盾する場合
C4パスがロジックの outcome 以外の場所で終了している、またはロジックが outcome を提供しない場合
C5結果に kind がない、kind に凡例がない、4つ以上の kind がある場合
C6ラベルがそのボックスよりも広い場合(13px 等幅フォント)
C7シナリオに、現実または例示かを示す origin と、その出典がない場合
C8ペアのシナリオが一緒に進行できない、または未知の場合
C9パネル行が、シナリオが欠落しているフィールドを読み取る場合
C10マトリックスセルが存在しないパネル行を指定している場合
C11ケースが、そのセルがまだ別の質問に依存している質問の下に表示される場合
C12ケースがマトリックスのどのセクションにもない、またはセクションが未知のケースを指定している場合
C13パネル行が、シナリオにないステップで表示されるように設定されている場合

C3 と C4 が重要です:コードが行わないことを述べるシナリオは公開できません。C6 は spec ではなくレイアウトを保護します:ボックスはラベルに合わせてサイズ設定されるため、layout.py がそうしなくなった場合にのみ発動します。新しいチェックが有効であることを証明するには、tests/ 内でその入力を一度壊してください。各チェックは build.py 内の1つの関数であり、このテーブルの ID の下で CHECKS にリストされています。

ビルドが spec をまったく読み取れない場合(キーがない、未知のノードへのエッジ、スローするポートなど)も、チェックが実行される前に、同じように平易な言葉で拒否されます。

デザインルール

  • 図ごとに1つの動く要素:単一のドット、一定の速度、一度に1ホップ。2つの図が並んでいる場合、同期して動きます。
  • 通過したエッジは実線、通過していないエッジは点線でグレー。パスから外れたノードはフェードします。
  • 色は結果の種類のみをエンコードします。ペアでは、最初の相違点(パネル値が異なる最初のステップ)はアンバー色で輪郭が描かれ、両側に ≠ がマークされ、パネルには − / + 列が表示されます。
  • 例示的なシナリオは、実際のケースがその結果に到達しない場合にのみ使用します。実際のケースの出典(チケット、レコード、測定値、日付)を記載します。
  • グリッドはセルごとに1つのフィールドを表示します。セルごとに3つのフィールドがあると、マトリックスが読みにくくなりました。
  • デフォルトはライトテーマ、prefers-color-scheme でダークテーマに切り替わります。Web フォントは使用しないため、ファイルはオフラインで動作します。

ファイル

パス役割
scripts/build.pyspec を読み取り、判定を取得し、チェックを実行し、ページとエクスポートを書き込みます。
scripts/runtime.htmlページ本体。build.py は、すでにフォーマットされた表示内容のみを渡し、spec の他の部分は渡しません。
scripts/layout.pyレイヤードレイアウト:ラベルに合わせたボックスサイズ、直交エッジ。
examples/refund-window/JS ポートと before/after ペアの例。
examples/free-shipping/グリッドの例:2つの未解決の質問。それぞれが影響を与えるケースについて決定されます。
examples/loyalty-tier/フォルダ自身の src/ に対する Oracle、そのグルーコード、および --export が書き込む fixture の例。

生成されるファイル(.truepath/、Oracle のスナップショットが保存される場所、および spec の隣にある *.html)はビルド出力です。ポートの例では、スキルを実行せずに確認できるように sim.html を保持しています。loyalty-tier は保持していません:そのフッターには判定を生成したコミットが記載されているため、ページはコミットごとに変化し、それを保持する git リポジトリ内でのみビルドされます。

制限

  • 図の種類は1つ:プロセスフロー。シーケンス図やアーキテクチャ図はビルドされません。
  • C6 は macOS(ui-monospace)で測定されます。より狭い Windows フォントでは余白が追加されるだけです。
  • ステップは宣言され、ロジックから導出されるわけではありません:C3 と C4 は間違った結果をキャッチしますが、間違った中間メッセージはキャッチしません。

関連スキル