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.