/visual-pr

name: visual-pr
description: "Posts a concise visual outline as a GitHub pull request comment. Use only when the user explicitly asks for visual-pr."
license: MIT
compatibility: Requires git, jq, and the GitHub CLI (gh)
user-invocable: true
disable-model-invocation: true
metadata:
  audience: all
  workflow: git

Visual PR

Post a compact visual explanation of a pull request as a comment. Do not replace or append to the pull request description.

Workflow

1. Find or create the pull request

gh pr view --json url,number,title,state,baseRefName,headRefName 2>/dev/null

• Use the open pull request for the current branch when one exists.
• If no pull request exists, inspect the branch, commit task changes when needed, push it, and create a draft pull

request according to the repository's conventions. Do not use the visual outline as the pull request body.

• Ask the user to select a pull request only when the current branch has no relevant work and there is no safe pull

request to create.

2. Understand the change

• Read the ticket and relevant task artifacts.
• Read the complete pull request diff and enough surrounding code to understand behavior and ownership.
• Use `gh pr view` to collect metadata and changed files.
• Identify only the contracts, responsibilities, and runtime paths that a reviewer needs to understand.

3. Write the visual outline

Read `$SKILL_PATH/references/comment-template.md`, then write the completed comment to a temporary file:

COMMENT_FILE=$(mktemp "${TMPDIR:-/tmp}/visual-pr-comment.XXXXXX")

Keep the outline concise:

• Explain **Why the change** in exactly one sentence.
• Put only reviewer warnings, migrations, compatibility constraints, deliberate omissions, or surprising decisions in

**Special things to note**. Use `- None.` when there are none.

• Make **Change outline** a structural view, not prose or a file-by-file changelog.
• Use one to three focused views: a data or API shape, pseudocode, a shallow file tree, a component tree, or a call,

control, or data flow.

• Prefer `diff` blocks for changes to an existing shape. Show the complete target shape when most of it is new.
• Use real names from the diff and omit categories that did not change.

4. Publish and verify the comment

COMMENT_URL=$("$SKILL_PATH/scripts/publish-comment.sh" <number> "$COMMENT_FILE")
test -n "$COMMENT_URL"
printf '%s\n' "$COMMENT_URL"
rm -f "$COMMENT_FILE"

The script adds a hidden `visual-pr` marker. It updates the current GitHub user's existing marked comment, or runs `gh pr comment` when none exists. Thus, one pull request has at most one visual-pr comment from that user. Never use `gh pr edit` for the visual outline because that replaces the pull request description.

5. Report completion

Reply with the pull request URL, the comment URL returned by GitHub, a two-sentence summary, and the verification that the comment command succeeded.

Write as one person to another. Use simple, concise language and avoid jargon.