visualize-plan

計画の可視化

計画された変更を、リスク分析、実行順序、影響指標を含む構造化された ASCII 図として描画します。各セクションは、レビュアーからの特定の質問に答えます。

基本原則： 装飾ではなく、可視化に判断を反映させます。

visualize-plan                          # Auto-detect from current branch
visualize-plan billing module redesign  # Describe the plan
visualize-plan #234                     # Pull from GitHub issue
visualize-plan --quick                  # Header + changes + impact, zero questions
visualize-plan --playground             # Skip straight to the HTML dashboard
visualize-plan --infographic            # Skip straight to NotebookLM

引数の解決

PLAN_INPUT = "$ARGUMENTS"    # Full argument string
PLAN_TOKEN = "$ARGUMENTS[0]" # First token — could be issue "#234" or plan description
# If starts with "#", treat as GitHub issue number. Otherwise, plan description.
# $ARGUMENTS (full string) for multi-word descriptions (CC 2.1.59 indexed access)

# Flags are stripped from PLAN_INPUT before it is used as a description:
#   --quick        → QUICK=true: tier-1 header + [1] Changes + [5] Impact, no Explore
#                    agent, no questions at all, no memory write. The 15-second answer.
#   --playground   → FORMATS=[ascii, playground]      (no format question)
#   --infographic  → FORMATS=[ascii, infographic]     (no format question)
#   --all          → FORMATS=[ascii, + everything the probe found]

質問の予算：最初の描画まではゼロ

以前は、1 文字も描画される前に、処理を止める質問を 3 つ（ソース、形式、セクションの順）行い、その後にさらに 4 つ目の質問をしていました。そのため、短時間で済む処理が glyph や手書き HTML に流れていました。

ASCII を描画するのに形式の回答は必要ありません。ASCII の最低限ルールにより、ユーザーが何を選んでも、まず ASCII を描画するからです。そのため、事前に質問しても得るものはなく、やり取りが 1 回増えるだけです。現在のルールは次のとおりです。

判断項目	タイミング	方法
ソース	事前	自動検出します。検出結果が本当に曖昧な場合（STEP 0）に限り質問します。
セクション	なし	既定ですべてを表示します。tier-1 ヘッダーが段階的な情報開示の役割を果たします。
形式	ASCII の後	描画後に 1 回質問し（STEP 5）、さらに詳しく掘り下げる質問と統合します。

--quick では、この 1 回の質問も省略します。

予算：Explore エージェントは最大 1 つ、描画後の質問（STEP 5）は 1 回までです。完了時点、または最初の上限に達した時点のいずれか早い方で停止して報告します。

---

重要：タスクの追跡

--quick では、このブロック全体を省略します。 15 秒で済む描画に依存関係グラフは不要です。タスク管理のオーバーヘッドのほうが、作業そのものより大きくなります。

# 1. Create main task IMMEDIATELY
TaskCreate(subject="Visualize plan: {PLAN_INPUT}", description="Plan visualization with ASCII rendering", activeForm="Analyzing plan context")

# 2. Create subtasks for each phase
TaskCreate(subject="Detect or clarify plan context", activeForm="Detecting plan context")          # id=2
TaskCreate(subject="Gather data and explore architecture", activeForm="Gathering plan data")       # id=3
TaskCreate(subject="Render tier 1 header", activeForm="Rendering header")                          # id=4
TaskCreate(subject="Render sections + dispatch to chosen format(s)", activeForm="Rendering sections") # id=5
TaskCreate(subject="Offer actions and store in memory", activeForm="Finalizing visualization")     # id=6

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Data gathering needs context first
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Header needs gathered data
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Sections need header rendered
TaskUpdate(taskId="6", addBlockedBy=["5"])  # Actions need sections done

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

STEP -1：過去の計画がないかメモリを確認する

# Search for related prior visualizations
mcp__memory__search_nodes(query="plan visualization {PLAN_INPUT}")
# If found, offer to compare with previous plan

STEP 0：計画のコンテキストを検出または確認する

まず、 scripts/detect-plan-context.sh を実行して自動検出を試みます。

bash "$SKILL_DIR/scripts/detect-plan-context.sh"

ブランチ名、イシュー番号（存在する場合）、コミット数、ファイル変更の概要が出力されます。

自動検出で明確な計画が見つかった場合（main から分岐したコミットがあるブランチ、または引数にイシュー番号がある場合）は、Step 1 に進みます。

曖昧な場合は、AskUserQuestion で確認します。

AskUserQuestion(
  questions=[{
    "question": "What should I visualize?",
    "header": "Source",
    "options": [
      {"label": "Current branch changes (Recommended)", "description": "Auto-detect from git diff against main"},
      {"label": "Describe the plan", "description": "I'll explain what I'm planning to change"},
      {"label": "GitHub issue", "description": "Pull plan from a specific issue number"},
      {"label": "Quick file diff only", "description": "Just show the change manifest, skip analysis"}
    ],
    "multiSelect": false
  }]
)

---

STEP 0.5：形式を調べる（サイレント — ここでは質問しない）

実際に利用できる形式だけを STEP 5 で提示できるよう、ここで機能を調べます。このステップでは何も質問しないでください。 詳しい手順は Read("references/format-dispatch.md") を参照してください。

場当たり的なチェックではなく、確立された MCP プローブのパターン Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/mcp-detection.md") を使用します。

# infographic is available IFF the notebooklm studio tool resolves:
ToolSearch(query="select:mcp__notebooklm-mcp__studio_create")
# chart-encoding is available IFF the bundled /dataviz skill resolves
# (CC >= 2.1.198, disableBundledSkills off). It is a MARK-layer upgrade
# applied WITHIN a format, not a 4th format — see chart-encoding-standard.md.

利用可能なものを AVAILABLE として記録します。ascii は常に利用可能です（最低限の形式）。playground は playground スキルがインストールされている場合に利用できます（ork に同梱）。infographic は、上で studio_create が解決できた場合に利用できます（サーバーに接続可能で、nlm login が完了している場合）。これとは別に、/dataviz スキルが解決できた場合は、そのフォームヒューリスティックと検証済みパレットを使って、ASCII 以外の形式でチャートのマークを強化します。解決できなかった場合、チャートは ASCII カードのままです。dataviz は必須ではありません。

そのうえで、質問はせずに FORMATS を設定します。

if   "--quick" in flags:        FORMATS = ["ascii"]              # and STEP 5 is skipped too
elif "--playground" in flags:   FORMATS = ["ascii", "playground"]
elif "--infographic" in flags:  FORMATS = ["ascii", "infographic"]
elif "--all" in flags:          FORMATS = AVAILABLE
else:                           FORMATS = ["ascii"]              # upgrade offered in STEP 5

ASCII の最低限ルール： 形式の選択にかかわらず、ASCII を最初にインラインで描画します。形式の選択に左右されないため、選択は STEP 5 まで延期でき、そこでの負担もありません。非同期の NotebookLM ジョブを await してはいけません。

---

STEP 1：データを収集する

正確な件数を得るために scripts/analyze-impact.sh を実行します。

bash "$SKILL_DIR/scripts/analyze-impact.sh"

次の情報が生成されます：アクション別（追加／変更／削除）のファイル数、行数、影響を受けるテストファイル、依存関係の変更。

--quick の場合はここで停止します — 影響分析スクリプトだけで、ヘッダー、[1] 変更、[5] 影響を作成できます。Explore エージェント、変更前後のマップ、メモリへの書き込みは行いません。

アーキテクチャレベルの理解と、既定の変更前後セクション [0] の作成のため、ベースとヘッドの両方でコンポーネントグラフをマッピングする Explore エージェントを起動します。

Agent(
  subagent_type="Explore",
  prompt="Map component architecture of {affected_directories} at TWO points: (a) base = each file as returned by `git show origin/main:<path>` (NOT the working tree, to avoid conflating uncommitted edits), (b) head = current working tree. Return per point: components, dependencies, data flows; mark what is added [+], removed [-], or changed [~] between them. Use the glyph skill for diagrams.",
  model="haiku",
  max_turns=15
)

差分にフロントエンド（*.tsx／*.css／ルートファイル）が含まれる場合は、デザイン面も変更前後の分析に含めるため、design-context-extract も実行します。パターンについては Read("references/before-after-arch-patterns.md") を参照してください。

これらのデータから、簡潔な 計画ブリーフ（Markdown）を作成します。これは、ASCII 以外のすべての形式が使用する唯一の受け渡し用データです（format-dispatch.md を参照）。

---

STEP 2: Tier 1 ヘッダーを描画する（常に）

assets/tier1-header.md テンプレートを使用します。フィールドの計算（リスクレベル、信頼度、可逆性）には Read("references/visualization-tiers.md") を読み込みます。

PLAN: {plan_name} ({issue_ref})  |  {phase_count} phases  |  {file_count} files  |  +{added} -{removed} lines
Risk: {risk_level}  |  Confidence: {confidence}  |  Reversible until {last_safe_phase}
Branch: {branch} -> {base_branch}

[0] Before/After  [1] Changes  [2] Execution  [3] Risks  [4] Decisions  [5] Impact  [all]

---

STEP 3: セクションを選択する（質問せず、すべてをデフォルトで選択）

6 つのセクションすべてを描画します。 これらがコンテンツです。どのセクションを描画するかを尋ねるのは、レビュー担当者が何も見る前に選択を求めることになります。tier-1 ヘッダーがすでに段階的開示のレイヤーになっており、説明する内容がないセクションは、理由を 1 行で示して省略します（内容を水増ししません）。そのため、「すべて」を選んでも「冗長」にはなりません。

SECTIONS = ["0","1","2","3","4","5"]      # default
if QUICK: SECTIONS = ["1","5"]            # --quick: change manifest + impact only

Explore マップに構造上の変更が示されている場合は、セクション [0] の Before/After を先頭にします。そうでない場合は、1 行の注記を添えて省略します。ユーザーがプロンプトで特定のセクション（「リスクだけ」など）を指定した場合は、それに従います。ただし、その指定を促す質問はしません。

---

STEP 4: 要求されたセクションを描画する

rules/section-rendering.md の規則に従って、要求された各セクションを描画します。ASCII パターンについては、対応するリファレンスを使用します。

セクション	リファレンス	主な規則
[0] Before/After アーキテクチャ	（references/before-after-arch-patterns.md を読み込む）	base と head を並べて表示する。[+]／[~]／[-] を付ける。構造上の変更がない場合は省略する
[1] 変更マニフェスト	（references/change-manifest-patterns.md を読み込む）	ファイルごとに [A]／[M]／[D] と +N -N を付ける
[2] 実行スイムレーン	（references/execution-swimlane-patterns.md を読み込む）	実行中は ===、ブロック中は ---、依存関係は | で示す
[3] リスクダッシュボード	（references/risk-dashboard-patterns.md を読み込む）	可逆性のタイムラインと 3 つのプレモーテム
[4] 意思決定ログ	（references/decision-log-patterns.md を読み込む）	ADR-lite：Context／Decision／Alternatives／Tradeoff
[5] 影響の概要	（assets/impact-dashboard.md を読み込む）	表：Added／Modified／Deleted／NET とテスト／API／依存関係

---

STEP 4b: フォーマットへの振り分け

STEP 0.5 で選択した FORMATS に、選択したセクションをレンダリングします。ASCII は常に最初にインラインでレンダリングします — ほかのフォーマットは同じ計画ブリーフを使用します。完全な表と委任パターンについては、Read("references/format-dispatch.md") を参照してください。

Format	Action
ASCII	ネイティブレンダリング（上記） — 常に実施する基本形
Playground	類型を分類し（下記）、計画ブリーフを playground スキルに渡す → docs/<branch-dir>/plan-viz.html を作成し、page-serve docs/<branch-dir>/plan-viz.html で配信して、出力された url= を返信の Open セクションに記載する（パスだけの記載や、手動で起動した http.server は不可）
Infographic	notebooklm の studio_create(artifact_type=infographic|slides) フローを実行する — 起動して通知し、studio_status をポーリングして、完了を待たない
All	ASCII を今すぐインラインで表示し、残りは完成次第リンクする
Charts (marks within Playground / Infographic)	定量的なマークを含むセクション — [3] Risk、[5] Impact、[6] Blast Radius — では、フォームを /dataviz（choosing-a-form）で選び、6 項目のチェック式でパレットを選んでから、validate_palette.js を実行します。バリデーターが FAIL になった場合、または /dataviz が存在しない場合は、ASCII カードレイアウトにフォールバックします。Chrome には ork トークン（playground-visual-standard.md の §2）を維持し、検証済みパレットを使うのはデータマークのみです。${CLAUDE_PLUGIN_ROOT}/shared/rules/chart-encoding-standard.md を参照してください。

<branch-dir> = / を -- に置き換えたブランチ名（PR Playground ゲートがチェックするものと同じパス）です。ファイル名は常に plan-viz.html です — index.html でも、トピック名でもありません。スラッグ検索とアーティファクトギャラリーが機能するには、名前を統一する必要があります。

Playground の類型： 計画の可視化は通常、DASHBOARD です — 2026-08 時点では、テンプレートを備えた第一級の類型であり、自由に作成してよいわけではありません。shared/assets/playground-exemplars/plan-dashboard.template.html をコピーし、plan-state アイランドを差し替えてください。CSS を一から書かないでください。このテンプレートには §2 のトークン、固定表示の tier-1 ヘッダー、<details> セクション [0]–[5]、各チャートに対応する表、コピー用プロンプトバー、モーション低減のゲートが含まれています。 計画で示す内容が ユーザー向けのフロー または 優先順位付け／意思決定 の場合は、user-story-player または decision-board の類型を選んでください。Read("${CLAUDE_PLUGIN_ROOT}/shared/rules/playground-visual-standard.md") の §0 のルーティングルールを適用し、完了とする前に §10 のセルフ監査を実行してください — DASHBOARD の行も含めます。

振り分け対象はバックログですか？ ユーザーが優先順位を付け、さらに実行へ振り分ける必要があるバックログの場合は、decision-router のバリアントを使ってください — 各カードは ork 戦略に振り分けられ、計画のみの呼び出しを出力します：Read("references/decision-router.md")。

継続する計画（複数ウェーブ）ですか？ 計画が複数のセッション／ウェーブにわたって実行される場合、またはコマンドで完了を検証できる場合は、living-plan の作例（living-plan.template.html）を使ってください。Playground には lpp-state の JSON ブロックが埋め込まれ、各項目には証拠に基づく「完了条件」が付与され、進捗は状態からレンダリングされます。

更新モード — パスではなく SLUG で検出します。 パスはブランチ名から生成されるため、ブランチ名を変更するとパスも変わります。パスをキーにしたチェックでは、計画が気付かないうちに別のファイルへ分岐してしまいます。作成の前に検索スクリプトを実行してください：

bash "$SKILL_DIR/scripts/find-living-plan.sh" "$SLUG"   # 0=更新する · 1=新規作成する · 2=すでに分岐しているため停止

終了コード 0 の場合は、スクリプトが出力したファイルにマージします（ステータスを切り替え、変更履歴を追記し、削除した項目を dropped に移動）。終了コード 2 の場合は、3 つ目のファイルを作成しないでください。両方のパスを示し、どちらを残すか尋ねてください。完全な仕様については、Read("references/format-dispatch.md") の §Living-plan update mode を参照してください。tests/orphans/test-duplicate-living-plans.sh によってゲートされています。

---

STEP 5：アクションを提示 — 1つだけ質問します

これはデフォルトの実行で唯一、処理を止めて確認する質問です。以前 STEP 0.5 で確認していた形式の選択も、ここで行います。--quick が指定されている場合、または形式がフラグで指定され、提示できる選択肢が残っていない場合は、質問を完全に省略します。 STEP 0.5 の確認で実際に見つかった内容から選択肢を作成してください。失敗するパスは決して提示しないでください。

options = []
if "playground" in AVAILABLE and "playground" not in FORMATS:
    options.append({"label": "Interactive dashboard (Recommended)",
                    "description": "Single-file HTML at docs/<branch-dir>/plan-viz.html, from plan-dashboard.template.html. Also satisfies the PR Playground gate. Multi-wave plans become LIVING plans, updated in place."})
if "infographic" in AVAILABLE and "infographic" not in FORMATS:
    options.append({"label": "NotebookLM infographic",
                    "description": "Stakeholder-ready infographic/slides. Async — fired and notified, never blocks."})
options.append({"label": "Drill deeper",
                "description": "Blast radius, cross-layer consistency, or migration checklist"})
options.append({"label": "Generate GitHub issues",
                "description": "One issue per execution phase, with labels, milestone, and blocked-by links"})

# AskUserQuestion caps at 4 options. "Done" must ALWAYS survive that cap — an
# actions menu with no exit is a trap — so reserve its slot instead of appending.
DONE = {"label": "Done", "description": "Plan visualization complete"}
AskUserQuestion(questions=[{"question": "What next?", "header": "Actions",
                           "options": options[:3] + [DONE], "multiSelect": False}])

上限のために選択肢から外れたものも、質問すれば利用できます。メニューは近道であり、すべての選択肢を網羅するものではありません。Write to designs/{branch}.md（テンプレート：assets/plan-report.md）もその一つです。

アップグレードでは、STEP 1 で作成した計画の概要を再利用します。再計算は不要です （references/format-dispatch.md を参照）。より詳細な形式が利用できない場合、質問はさらに掘り下げる／課題／完了の選択肢になります。

ファイルに書き込む： assets/plan-report.md テンプレートを使用して、レポート全体を designs/{branch-name}.md に保存します。

課題を生成する： 各実行フェーズについて、タイトルが [{component}] {phase_description}、ラベルがコンポーネントと risk:{level}、マイルストーン、計画の各セクションを本文とし、ブロック元への参照を含む GitHub issue を作成します。

メモリに保存する： 将来の比較に使えるよう、計画の要約をナレッジグラフに保存します。

mcp__memory__create_entities(entities=[{
  "name": "Plan: {plan_name}",
  "entityType": "plan-visualization",
  "observations": [
    "Branch: {branch}",
    "Risk: {risk_level}, Confidence: {confidence}",
    "Phases: {phase_count}, Files: {file_count}",
    "Key decisions: {decision_summary}"
  ]
}])

---

詳細分析（Tier 3、リクエスト時）

ユーザーが「さらに掘り下げる」を選択した場合に利用できます。レイヤー横断のパターンと移行パターンについて、Read("references/deep-dives.md") を読み込みます。

セクション	内容	リファレンス
[6] 影響範囲	影響の同心円（直接 -> 推移的 -> テスト）	（references/blast-radius-patterns.md を読み込み）
[7] レイヤー横断の整合性	ギャップの検出を含む、フロントエンド／バックエンドのエンドポイントの整合性	（references/deep-dives.md を読み込み）
[8] 移行チェックリスト	順次／並列のブロックと所要時間の見積もりを含む、順序付きの手順書	（references/deep-dives.md を読み込み）

---

主な原則

原則	適用方法
段階的な開示	Tier 1 のヘッダーは常に表示し、セクションはリクエスト時に表示します
装飾より判断	すべてのセクションで、レビュー担当者の疑問に答えます
推定より正確さ	ファイル数や行数のカウントにはスクリプトを使います
不確実性に誠実であること	確信度、事前検証、トレードオフのコストを示します
実行可能な出力	ファイルへの書き込み、課題の生成、さらなる掘り下げを行います
質の低い生成物を避ける	汎用的なつなぎの文句、見せかけの精密さ、未使用のセクションを避けます

ルールのクイックリファレンス

ルール	影響	対象
section-rendering（rules/section-rendering.md を読み込み）	高	6つのコアセクション（[0]–[5]）すべてのレンダリング規約
ASCII 図	中	glyph スキルを使用（枠線、ファイルツリー、ワークフロー）

リファレンス

Read("references/<file>") で必要に応じて読み込みます。

ファイル	内容
visualization-tiers.md	段階的な開示の階層とヘッダーフィールドの算出
change-manifest-patterns.md	変更マニフェストの ASCII パターン
execution-swimlane-patterns.md	実行スイムレーンの ASCII パターン
risk-dashboard-patterns.md	リスクダッシュボードの ASCII パターン
decision-log-patterns.md	意思決定ログの ASCII パターン
blast-radius-patterns.md	影響範囲の ASCII パターン
deep-dives.md	レイヤー横断の整合性と移行チェックリスト
format-dispatch.md	出力形式の機能確認、ASCII 最低基準ルール、playground/notebooklm への委任
before-after-arch-patterns.md	出力形式ごとのセクション [0] の変更前／変更後のアーキテクチャ

例（初回実行の前に1つ読んでください）

入力、実際のASCII出力、生成された成果物が揃った、手順を最後まで示す例です。各例のASCIIパターンは references/*-patterns.md と完全に一致しているため、そのまま安心して参考にできます。

ファイル	内容
examples/01-dashboard-run.md	デフォルトの流れを最初から最後まで示します：検出 → 収集 → ヘッダー → 6つのセクションすべて → 1つの質問 → 生成されたHTML。plan-dashboard.template.html のサンプル状態と同じシナリオです。
examples/02-living-plan-update.md	名前変更されたブランチでの更新モード：スラッグをキーにした検出、JSONのマージ、エビデンスゲート、終了コード2の分岐ケースを示します。
examples/03-quick-run.md	--quick：省略される内容、出力の見た目、決して捏造してはならない内容を示します。

アセット

必要に応じて Read("assets/<file>") で読み込みます：

ファイル	内容
plan-report.md	Mustache形式の完全なレポートテンプレート
impact-dashboard.md	影響テーブルのテンプレート
tier1-header.md	5行の要約テンプレート

品質基準

以下をすべて満たせば完了です：

• Tier 1 ヘッダーには、リスク、確信度、可逆性、ブランチ、ファイル数、行数のすべての項目が必ず入力されます。
• ファイル数と行数は、推定や推測ではなく、scripts/analyze-impact.sh から取得します。
• 描画される各セクションは、レビュー担当者の質問に答えます。内容のないセクションは、埋め合わせをせず、1行の理由を添えて省略します。
• セクション [3] では、不可逆点をフェーズIDで明示します（--- POINT OF NO RETURN (after P3) ---）。ほのめかすだけでは不十分です。また、各プレモーテムではカテゴリーではなくメカニズム（トリガー、順序、結果として生じる不正な状態）を記述します。「移行リスク」は見出しです。「処理中のリトライキューがインラインの課金経路を参照したままP2をリリースすると、同じ請求書に二度課金される」はプレモーテムです。これはセクションで測定する失敗モードであり、文体の好みではありません。rules/section-rendering.md §[3] には、どちらにも反証可能なテストが定められています。
• セクション [0] では、ベース（git show origin/main:<path>）とヘッド（作業ツリー）を比較し、各ノードに [+]／[~]／[-] を付けます。構造に変更がない場合は、注記を添えて省略します。
• 選択した形式にかかわらず、ASCIIを最初に、インラインで描画します。非同期の形式（インフォグラフィックなど）は実行を通知しますが、完了を待ちません。
• プランの要約は、セッションをまたいだ比較のためにメモリのナレッジグラフへ保存されます（--quick では省略）。
• 最初の描画前に、進行を妨げる質問は一切ありません。 ソースは自動検出され（本当に曖昧な場合に限り質問します）、セクションはすべて選択した状態をデフォルトとし、形式はASCIIのベースラインがすでに表示された後に選択されます。1回の実行で質問は最大1つで、--quick では質問しません。
• plan-dashboard.template.html（または §0 のルーティングルールで選ばれた living-plan／player／board の見本）から開始したプレイグラウンド出力を使用し、手作りのCSSは使いません。また、DASHBOARDの行を含む§10のセルフ監査に合格しています。
• 作成前に scripts/find-living-plan.sh でスラッグを使ってliving planを検索し、既存のプランを2つ目のファイルに分岐させず、その場で更新します。

関連スキル

• ork:implement - 計画された変更を実行する
• ork:explore - 現在のアーキテクチャを把握する
• ork:assess - 複雑さとリスクを評価する
• ork:memory - 過去のプランの可視化を検索する
• ork:remember - 将来参照するためにプランの決定事項を保存する