Help us improve
Share bugs, ideas, or general feedback.
From ork
Visualizes planned code changes as ASCII diagrams with before/after architecture, risk analysis, execution order, and impact metrics. Use for reviewing plans, migrations, or assessing change impacts.
npx claudepluginhub yonatangross/orchestkit --plugin orkHow this skill is triggered — by the user, by Claude, or both
Slash command
/ork:visualize-planThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Render planned changes as structured ASCII visualizations with risk analysis, execution order, and impact metrics. Every section answers a specific reviewer question.
assets/impact-dashboard.mdassets/plan-report.mdassets/tier1-header.mdreferences/blast-radius-patterns.mdreferences/change-manifest-patterns.mdreferences/decision-log-patterns.mdreferences/deep-dives.mdreferences/execution-swimlane-patterns.mdreferences/risk-dashboard-patterns.mdreferences/visualization-tiers.mdrules/_sections.mdrules/_template.mdrules/section-rendering.mdscripts/analyze-impact.shscripts/detect-plan-context.shtest-cases.jsonReviews implementation plans as interactive HTML reports with architecture diagrams, blast radius analysis, risk assessment, and gap detection. Activates for plan review requests like 'check my plan' or 'is this feasible'.
Analyzes pull requests for architectural impact, generating before/after diagrams, business effects, enabled features, and risks for decision makers.
Creates a visual code review on a Miro board from a PR/MR, local changes, or branch comparison. Produces file-change tables, architecture/security docs, and diagrams, then links them back to the PR/MR.
Share bugs, ideas, or general feedback.
Render planned changes as structured ASCII visualizations with risk analysis, execution order, and impact metrics. Every section answers a specific reviewer question.
Core principle: Encode judgment into visualization, not decoration.
/ork:visualize-plan # Auto-detect from current branch
/ork:visualize-plan billing module redesign # Describe the plan
/ork:visualize-plan #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)
TaskCreate(subject="Visualize plan: {PLAN_INPUT}", description="Plan visualization with ASCII rendering", activeForm="Analyzing plan context")
# Search for related prior visualizations
mcp__memory__search_nodes(query="plan visualization {PLAN_INPUT}")
# If found, offer to compare with previous plan
First, attempt auto-detection by running scripts/detect-plan-context.sh:
bash "$SKILL_DIR/scripts/detect-plan-context.sh"
This outputs branch name, issue number (if any), commit count, and file change summary.
If auto-detection finds a clear plan (branch with commits diverging from main, or issue number in args), proceed to Step 1.
If ambiguous, clarify with 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
}]
)
Run scripts/analyze-impact.sh for precise counts:
bash "$SKILL_DIR/scripts/analyze-impact.sh"
This produces: files by action (add/modify/delete), line counts, test files affected, and dependency changes.
For architecture-level understanding, spawn an Explore agent on the affected directories:
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"
)
Use assets/tier1-header.md template. Load Read("${CLAUDE_SKILL_DIR}/references/visualization-tiers.md") for field computation (risk level, confidence, reversibility).
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]
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
}]
)
Render each requested section following ${CLAUDE_SKILL_DIR}/rules/section-rendering.md conventions. Use the corresponding reference for ASCII patterns:
| Section | Reference | Key Convention |
|---|---|---|
| [1] Change Manifest | (load ${CLAUDE_SKILL_DIR}/references/change-manifest-patterns.md) | [A]/[M]/[D] + +N -N per file |
| [2] Execution Swimlane | (load ${CLAUDE_SKILL_DIR}/references/execution-swimlane-patterns.md) | === active, --- blocked, | deps |
| [3] Risk Dashboard | (load ${CLAUDE_SKILL_DIR}/references/risk-dashboard-patterns.md) | Reversibility timeline + 3 pre-mortems |
| [4] Decision Log | (load ${CLAUDE_SKILL_DIR}/references/decision-log-patterns.md) | ADR-lite: Context/Decision/Alternatives/Tradeoff |
| [5] Impact Summary | (load ${CLAUDE_SKILL_DIR}/assets/impact-dashboard.md) | Table: Added/Modified/Deleted/NET + tests/API/deps |
After rendering, offer next steps:
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
}]
)
Write to file: Save full report to designs/{branch-name}.md using assets/plan-report.md template.
Generate issues: For each execution phase, create a GitHub issue with title [{component}] {phase_description}, labels (component + risk:{level}), milestone, body from plan sections, and blocked-by references.
Store in memory: Save plan summary to knowledge graph for future comparison:
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}"
]
}])
Available when user selects "Drill deeper". Load Read("${CLAUDE_SKILL_DIR}/references/deep-dives.md") for cross-layer and migration patterns.
| Section | What It Shows | Reference |
|---|---|---|
| [6] Blast Radius | Concentric rings of impact (direct -> transitive -> tests) | (load ${CLAUDE_SKILL_DIR}/references/blast-radius-patterns.md) |
| [7] Cross-Layer Consistency | Frontend/backend endpoint alignment with gap detection | (load ${CLAUDE_SKILL_DIR}/references/deep-dives.md) |
| [8] Migration Checklist | Ordered runbook with sequential/parallel blocks and time estimates | (load ${CLAUDE_SKILL_DIR}/references/deep-dives.md) |
| Principle | Application |
|---|---|
| Progressive disclosure | Tier 1 header always, sections on request |
| Judgment over decoration | Every section answers a reviewer question |
| Precise over estimated | Use scripts for file/line counts |
| Honest uncertainty | Confidence levels, pre-mortems, tradeoff costs |
| Actionable output | Write to file, generate issues, drill deeper |
| Anti-slop | No generic transitions, no fake precision, no unused sections |
| Rule | Impact | What It Covers |
|---|---|---|
section-rendering (load ${CLAUDE_SKILL_DIR}/rules/section-rendering.md) | HIGH | Rendering conventions for all 5 core sections |
| ASCII diagrams | MEDIUM | Via ascii-visualizer skill (box-drawing, file trees, workflows) |
Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):
| File | Content |
|---|---|
visualization-tiers.md | Progressive disclosure tiers and header field computation |
change-manifest-patterns.md | Change manifest ASCII patterns |
execution-swimlane-patterns.md | Execution swimlane ASCII patterns |
risk-dashboard-patterns.md | Risk dashboard ASCII patterns |
decision-log-patterns.md | Decision log ASCII patterns |
blast-radius-patterns.md | Blast radius ASCII patterns |
deep-dives.md | Cross-layer consistency and migration checklist |
Load on demand with Read("${CLAUDE_SKILL_DIR}/assets/<file>"):
| File | Content |
|---|---|
plan-report.md | Full mustache-style report template |
impact-dashboard.md | Impact table template |
tier1-header.md | 5-line summary template |
ork:implement - Execute planned changesork:explore - Understand current architectureork:assess - Evaluate complexity and risksork:memory - Search prior plan visualizationsork:remember - Store plan decisions for future reference