figure-spec

FigureSpec：決定論的な JSON → SVG 図の生成

レビュー担当者の各スロットの前に、Selectable Reviewers に従ってください： 呼び出しを解決 → .aris/reviewer.json → Claude Code のデフォルト（Codex MCP） を、正規ヘルパーリゾルバー経由で reviewer_route.py を使用して設定し、 このスロットのティア、新しいコンテキスト、ソース／画像入力、決定論的なゲートを維持します。 以下の Codex の例／固定設定は backend=codex にのみ適用されます。他のルートでは、 それぞれ独自の初回呼び出し／応答の契約を使用します。ルートと実際に返された ID を保存し、 選択できない場合は REVIEW_UNAVAILABLE とします。実際のファミリー／完了状況／スコープに基づいて 採否を分類します。呼び出し時の reviewer/model/effort の上書き設定は、 レビュアーを使用する子プロセスに引き継ぎます。生成ワーカーは変更されません。

決定論的な JSON → SVG レンダラーを使用して、編集可能な SVG ベクター画像として、出版品質のアーキテクチャ図、ワークフローパイプライン、監査カスケード、システムトポロジーを生成します。

このスキルを使用する場合

figure-spec を使用してください：

• システムアーキテクチャ図（階層型、ハブ・アンド・スポーク型、マルチプレーン型）
• ワークフロー／パイプライン図
• 監査カスケード／フロー制御図
• ノードの位置、接続、グループ化が意味的に重要な構造化図
• 後から編集／調整する必要がある図（SVG はプレーンテキストです）
• 決定性が重要な図（同じ仕様 → 同じ SVG）

次の場合は使用しないでください：

• データプロット（棒グラフ／折れ線グラフ／散布図）— /paper-figure を使用してください
• 自然な／定性的なイラスト — /paper-illustration を使用してください
• 簡単なステートマシン／フローチャート — /mermaid-diagram を使用してください（より簡潔な構文）

主な特性

• 決定論的：同一の FigureSpec JSON は常に同一の SVG 出力を生成します（レンダラーのバージョンとフォントが固定の場合）
• 編集可能：SVG 出力はプレーンテキストで、手動またはプログラムによる後編集が可能です
• 検証機能：レンダラーがスキーマを適用し、不正な仕様を明確なエラーメッセージとともに拒否します
• 形状認識：エッジのクリッピングは、矩形／角丸矩形／円／楕円／ひし形で正しく機能します
• CJK サポート：中国語文字の幅を適切に推定し、複数行ラベルに対応します
• 外部 API 不要：ネットワークや API キーを使用せず、完全にローカルで動作します

ツールの場所

Phase 3.1（Arch C）の移行により、正規の実装は skills/figure-spec/scripts/figure_renderer.py（この SKILL 自身の scripts/ サブディレクトリ）に配置されています。後方互換性を保つための tools/figure_renderer.py シムは os.execv を介して正規ファイルに転送するため、 .aris/tools/figure_renderer.py を使用する既存ユーザーや、 tools/figure_renderer.py を手動でコピーしたユーザーも そのまま利用できます。

ハイブリッドチェーンで $FIGURE_RENDERER を解決します（レイヤー 0 は 所有元の SKILL にある自己完結型の場所を優先します。レイヤー 1〜4 は shared-references/integration-contract.md §2、 Policy A — スキルローカルのゲートに記載された共有ランタイムチェーンです）。

# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
FIGURE_RENDERER=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/figure_renderer.py" ]; then
  FIGURE_RENDERER="$CLAUDE_SKILL_DIR/scripts/figure_renderer.py"
fi
# Layers 1-4: shared-runtime chain (legacy compatibility + non-CC hosts).
if [ -z "$FIGURE_RENDERER" ]; then
  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
  if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
      ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
  fi
  if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
      ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
  fi
  FIGURE_RENDERER=".aris/tools/figure_renderer.py"
  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER="tools/figure_renderer.py"
  [ -f "$FIGURE_RENDERER" ] || { [ -n "${ARIS_REPO:-}" ] && FIGURE_RENDERER="$ARIS_REPO/tools/figure_renderer.py"; }
  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER=""
fi
[ -z "$FIGURE_RENDERER" ] && {
  echo "ERROR: figure_renderer.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-4: .aris/tools/, tools/, \$ARIS_REPO/tools/, \$ARIS_REPO/tools/ via ~/.aris/repo)." >&2
  echo "       /figure-spec cannot produce SVG output. Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), or copy the helper from \$ARIS_REPO/skills/figure-spec/scripts/." >&2
  exit 1
}

呼び出し：

python3 "$FIGURE_RENDERER" render <spec.json> --output <out.svg>
python3 "$FIGURE_RENDERER" validate <spec.json>
python3 "$FIGURE_RENDERER" schema

ワークフロー

ステップ 1：図の目的を把握する

$ARGUMENTS（説明、または PAPER_PLAN.md／NARRATIVE_REPORT.md へのパス）から、以下を特定します：

• 目的：アーキテクチャ、ワークフロー、パイプライン、監査カスケード、トポロジーのどれですか？
• 主なエンティティ：ボックスに何を配置しますか？
• 関係性：どのように接続しますか？（使用する、生成する、呼び出す、検証する、連鎖する）
• グループ化：エンティティを名前付きの領域にまとめますか？
• 階層かネットワークか：積層、左から右へのフロー、中央ハブのどれですか？

ステップ 2：FigureSpec JSON を作成する

キャンバスサイズの目安：

• 1 段組みの図：約 500×350 px
• 2 段組み（全幅）：約 900×500 px
• 縦長のトポロジー：約 700×700 px

図の種類に応じたテンプレートから始めます：

アーキテクチャ（積層行）：

{
  "canvas": {"width": 900, "height": 520},
  "nodes": [
    {"id": "layer1_label", "label": "Layer 1", "x": 450, "y": 60, ...},
    {"id": "node_a", "label": "A", "x": 180, "y": 120, ...},
    {"id": "node_b", "label": "B", "x": 350, "y": 120, ...}
  ],
  "edges": [...],
  "groups": [
    {"label": "Layer 1", "node_ids": ["node_a", "node_b"], "fill": "#F0F9FF", "stroke": "#BAE6FD"}
  ]
}

ワークフロー（左から右への連鎖）：

{
  "canvas": {"width": 900, "height": 300},
  "nodes": [
    {"id": "step1", "label": "Step 1", "x": 100, "y": 150, "shape": "rounded"},
    {"id": "step2", "label": "Step 2", "x": 280, "y": 150, "shape": "rounded"}
  ],
  "edges": [
    {"from": "step1", "to": "step2", "label": "produces"}
  ]
}

判断のひし形：

{"id": "check", "label": "Passes?", "shape": "diamond", "x": 450, "y": 200}

ステップ 3：レンダリングして検証する

# Validate first ($FIGURE_RENDERER was resolved in "Tool Location" above)
python3 "$FIGURE_RENDERER" validate /tmp/spec.json

# Render to SVG
python3 "$FIGURE_RENDERER" render /tmp/spec.json --output figures/fig_arch.svg

# Convert to PDF for LaTeX inclusion
rsvg-convert -f pdf figures/fig_arch.svg -o figures/fig_arch.pdf

検証に失敗した場合は、エラー（フィールドの不足、ID の重複、重なりの警告、無効な 16 進カラーコード）を確認し、JSON を修正します。

ステップ 4：目視レビュー

SVG/PDF を開き、次の点を確認します。

• 重なりがないこと：ノード同士やグループの境界と衝突していない
• 読みやすさ：フォントサイズが統一され、ラベルが切れていない
• エッジの明瞭さ：矢印が適切な角度でノードに接続し、エッジ付近のラベルが読みやすい
• グループの整列：背景の長方形でメンバーがきれいに囲まれている
• 色の区別：色とグレースケールのどちらでもカテゴリを視覚的に区別できる

問題が見つかった場合は、JSON 仕様を編集して再レンダリングします（生成された SVG は編集しないでください）。

ステップ 5：Codex レビューで反復する（任意、重要度の高い図向け）

論文のアーキテクチャ図では、複数モデルによるレビューを実行します。

まずこのレビュースロットを解決してください。以下は backend=codex の例です。

mcp__codex__codex:
  model: gpt-6-astra
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    Review this SVG figure for a technical paper (architecture / workflow diagram).

    Spec file: /path/to/spec.json
    Rendered: /path/to/fig.svg

    Evaluate:
    1. Clarity (C): can a reader understand the system from this figure alone?
    2. Readability (R): font sizes, label placement, visual hierarchy
    3. Semantic accuracy (S): do relationships match the described system?

    Score each axis 1-10 and list specific issues to fix.

3 つの評価軸すべてが 7/10 以上になるまで反復します。ARIS の技術レポートの図は、このループを 5 回繰り返し、C:7/R:7/S:8 に到達しました。

スキーマのクイックリファレンス

正式なスキーマを確認するには、python3 "$FIGURE_RENDERER" schema を実行します（上記の「ツールの場所」に従って $FIGURE_RENDERER を解決してください）。

ノード

フィールド	必須	デフォルト	備考
id	✓	—	一意
label	✓	—	複数行の場合は \n
x, y	✓	—	中心座標
width, height		120, 50
shape		rounded	rect / rounded / circle / ellipse / diamond
fill, stroke		パレットから自動設定	#RRGGBB
text_color		#333333
font_size		14	スタイルのデフォルト値を上書き

エッジ

フィールド	デフォルト	備考
from, to	必須	同じ場合は自己ループ
label	—	エッジの短いラベル
style	solid	solid / dashed / dotted
color	#555555
curve	false	曲線のパス

グループ

複数のノードを囲む長方形の背景領域：

{"label": "Layer Name", "node_ids": ["a", "b", "c"], "fill": "#EFF6FF", "stroke": "#BFDBFE"}

デザインパターン

パターン 1：レイヤー型アーキテクチャ

関連するノードを行ごとに並べ、各行をグループにします。レイヤー間には意味を示すラベル（uses↓、produces↑、checks↓）付きの矢印を追加します。

パターン 2：ハブ・アンド・スポーク

中央にノード（例：Executor）、周辺にノード（スキル、ツール）を配置します。主要な関係には実線の矢印、フィードバックには破線の矢印を使います。

パターン 3：フィードバック付きパイプライン

メインフローを左から右に配置し、フィードバックの矢印は curve: true を指定して下側に曲線で描きます。

パターン 4：監査カスケード

上から入力が流入し、右へ出力が流出する 3 段階の水平カスケードにします。各段階はそれぞれグループ内に配置します。

アンチパターン

• 階層構造としてグループを使わない：グループは同列のノードを囲むものであり、包含関係を示すものではありません
• グループを入れ子にしない：レンダラーはグループを背景の長方形として描画するため、入れ子にするとマトリョーシカのように見えます
• 長い対角線を交差させない：矢印が 3 行以上を横切る場合は、レイアウトを見直してください
• 同じ役割のノードでフォントサイズを混在させない：ノードのカテゴリごとにサイズを統一してください

出力要件

• figures/ に SVG ファイル（ベクター形式で、編集可能かつ手動調整可能）
• 再現性を確保するため、ソースの FigureSpec JSON を figures/specs/ に保存
• LaTeX に含める PDF 版を rsvg-convert で作成

他のスキルとの連携

• /paper-writing（ワークフロー 3）：illustration: figurespec（アーキテクチャ図のデフォルト）の場合、このスキルがフェーズ 2b を担当します
• /paper-figure：データプロットを担当します。両者は相互に補完し、データとアーキテクチャを合わせて図一式を完成させます
• /paper-illustration：自然な表現や定性的なスタイルが必要な図（写真を使った手法の図解、定性的な結果のグリッドなど）向けの代替手段です
• /mermaid-diagram：シンプルなフローチャート向けの軽量な代替手段です

レビューのトレース

各 mcp__codex__codex または mcp__codex__codex-reply のレビュアー呼び出し後、shared-references/review-tracing.md に従ってトレースを保存します（ポリシー C — フォレンジック。決して黙って省略しないでください）。save_trace.sh（shared-references/integration-contract.md §2 の手順に従って解決）を使用するか、.aris/traces/<skill>/<date>_run<NN>/ にファイルを直接書き込みます。--- trace: パラメーター（デフォルト：full）に従ってください。