plan-viz

計画の可視化

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

基本原則： 装飾ではなく、可視化に判断を組み込みます。

/ork:plan-viz                          # Auto-detect from current branch
/ork:plan-viz billing module redesign  # Describe the plan
/ork:plan-viz #234                     # Pull from GitHub issue

引数の解決

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)

---

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

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

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

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

自動検出で明確な計画が見つかった場合（main から分岐してコミットがあるブランチ、または引数にイシュー番号が指定されている場合）、ステップ 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", "markdown": "```\nBranch Diff Analysis\n────────────────────\n$ git diff main...HEAD\n\n→ File change manifest (+A, M, -D)\n→ Execution swimlane by phase\n→ Risk dashboard + pre-mortems\n→ Impact summary (lines, tests, API)\n```"},
      {"label": "Describe the plan", "description": "I'll explain what I'm planning to change", "markdown": "```\nPlan Description\n────────────────\nYou describe → I visualize:\n\n→ Before/after architecture diagrams\n→ Execution order with dependencies\n→ Risk analysis per component\n→ Decision log (ADR-lite format)\n```"},
      {"label": "GitHub issue", "description": "Pull plan from a specific issue number", "markdown": "```\nGitHub Issue Source\n───────────────────\n$ gh issue view #N\n\n→ Extract requirements from body\n→ Map to file-level changes\n→ Generate execution phases\n→ Link back to issue for tracking\n```"},
      {"label": "Quick file diff only", "description": "Just show the change manifest, skip analysis", "markdown": "```\nQuick File Diff\n───────────────\n[A] src/new-file.ts        +120\n[M] src/existing.ts    +15  -8\n[D] src/old-file.ts        -45\n─────────────────────────────\nNET: +82 lines, 3 files\n\nNo risk analysis or swimlanes\n```"}
    ],
    "multiSelect": false
  }]
)

---

STEP 1：データを収集する

正確な数を把握するため、scripts/analyze-impact.sh を実行します。

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

ファイルの操作別（追加／変更／削除）、行数、影響を受けるテストファイル、依存関係の変更が出力されます。

アーキテクチャレベルで把握するには、影響を受けるディレクトリを対象に Explore エージェントを起動します。

Agent(
  subagent_type="Explore",
  prompt="Explore the architecture of {affected_directories}. Return: component diagram, key data flows, health scores per module. Use the ascii-visualizer skill for diagrams.",
  model="haiku"
)

---

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

assets/tier1-header.md テンプレートを使用します。フィールドの算出（リスクレベル、信頼度、可逆性）には Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/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}

[1] Changes  [2] Execution  [3] Risks  [4] Decisions  [5] Impact  [all]

---

STEP 3：展開するセクションを確認する

AskUserQuestion(
  questions=[{
    "question": "Which sections to render?",
    "header": "Sections",
    "options": [
      {"label": "All sections", "description": "Full visualization with all 5 core sections", "markdown": "```\n[1] Change Manifest   [A]/[M]/[D] file tree\n[2] Execution         Swimlane with phases\n[3] Risks             Dashboard + pre-mortems\n[4] Decisions         ADR-lite decision log\n[5] Impact            Lines, tests, API, deps\n```"},
      {"label": "Changes + Execution", "description": "File diff tree and execution swimlane", "markdown": "```\n[1] Change Manifest\n    [M] src/auth.ts         +45 -12\n    [A] src/oauth.ts        +89\n\n[2] Execution Swimlane\n    Phase 1 ====[auth]========▶\n    Phase 2 ----[blocked]--===▶\n```"},
      {"label": "Risks + Decisions", "description": "Risk dashboard and decision log", "markdown": "```\n[3] Risk Dashboard\n    MEDIUM ██░░ migration reversible\n    HIGH   ███░ API breaking change\n    Pre-mortem: \"What if auth fails?\"\n\n[4] Decision Log\n    D1: OAuth2 over JWT (security)\n    D2: Postgres over Redis (durability)\n```"},
      {"label": "Impact only", "description": "Just the numbers: files, lines, tests, API surface", "markdown": "```\n[5] Impact Summary\n    ┌──────────┬─────┬───────┐\n    │ Metric   │Count│ Delta │\n    ├──────────┼─────┼───────┤\n    │ Files    │  12 │  +3   │\n    │ Lines    │ 450 │ +127  │\n    │ Tests    │   8 │  +4   │\n    │ API sfc  │   3 │  +1   │\n    └──────────┴─────┴───────┘\n```"}
    ],
    "multiSelect": false
  }]
)

---

STEP 4：指定されたセクションを描画する

${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/rules/section-rendering.md の規約に従って、指定された各セクションを描画します。ASCII パターンについては、対応するリファレンスを参照します。

セクション	リファレンス	主な規約
[1] 変更一覧	(${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/change-manifest-patterns.md を読み込む)	ファイルごとに [A]／[M]／[D] と +N -N
[2] 実行スイムレーン	(${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/execution-swimlane-patterns.md を読み込む)	=== は実行中、--- はブロック中、| は依存関係
[3] リスクダッシュボード	(${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/risk-dashboard-patterns.md を読み込む)	可逆性のタイムラインと 3 つの事前検証
[4] 意思決定ログ	(${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/decision-log-patterns.md を読み込む)	ADR-lite：コンテキスト／決定／代替案／トレードオフ
[5] 影響の概要	(${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/assets/impact-dashboard.md を読み込む)	表：追加／変更／削除／純計 + テスト／API／依存関係

---

STEP 5：アクションを提案する

描画後、次のステップを提案します。

AskUserQuestion(
  questions=[{
    "question": "What next?",
    "header": "Actions",
    "options": [
      {"label": "Write to designs/", "description": "Save as designs/{branch}.md for PR review", "markdown": "```\nSave to File\n────────────\ndesigns/\n  └── feat-billing-redesign.md\n      ├── Header + metadata\n      ├── All rendered sections\n      └── Ready for PR description\n```"},
      {"label": "Generate GitHub issues", "description": "Create issues from execution phases with labels and milestones", "markdown": "```\nGitHub Issues\n─────────────\n#101 [billing] Phase 1: Schema migration\n     labels: component:billing, risk:medium\n#102 [billing] Phase 2: API endpoints\n     labels: component:billing, risk:low\n     blocked-by: #101\n```"},
      {"label": "Drill deeper", "description": "Expand blast radius, cross-layer check, or migration checklist", "markdown": "```\nDeep Dive Options\n─────────────────\n[6] Blast Radius\n    direct → transitive → test impact\n[7] Cross-Layer Consistency\n    Frontend ↔ Backend endpoint gaps\n[8] Migration Checklist\n    Ordered runbook with time estimates\n```"},
      {"label": "Done", "description": "Plan visualization complete"}
    ],
    "multiSelect": false
  }]
)

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

イシューを作成する： 実行フェーズごとに、タイトルを [{component}] {phase_description}、ラベルを（コンポーネント + risk:{level}）、マイルストーンを設定し、計画セクションを本文に含め、ブロック元の参照を記載した GitHub イシューを作成します。

---

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

ユーザーが「さらに詳しく」を選択した場合に利用できます。レイヤー横断および移行パターンについては、Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/deep-dives.md") を読み込みます。

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

主要原則

原則	適用方法
段階的な開示	ティア 1 のヘッダーは常に表示し、セクションは要求に応じて表示します
装飾より判断	各セクションで、レビュー担当者の疑問に答えます
推定より正確さ	ファイル数や行数のカウントにはスクリプトを使用します
不確実性を正直に示す	確信度、事前検証、トレードオフのコストを示します
実行可能な出力	ファイルへの書き込み、課題の生成、詳細の掘り下げを行います
無駄な記述を避ける	汎用的なつなぎ表現、見せかけの精密さ、使われないセクションをなくします

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

ルール	影響	対象
section-rendering（${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/rules/section-rendering.md を読み込む）	HIGH	5 つのすべてのコアセクションの表示規約
ASCII 図	MEDIUM	ascii-visualizer スキルを使用（ボックス描画、ファイルツリー、ワークフロー）

参考資料

Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/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	レイヤー間の整合性と移行チェックリスト

アセット

Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/assets/<file>") を使って、必要に応じて読み込みます：

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

関連スキル

• ork:implement - 計画した変更を実行します
• ork:explore - 現在のアーキテクチャを理解します
• ork:assess - 複雑さとリスクを評価します