iru-pr-description
Check the current branch's code changes and draft a brief, concise pull request description (emojis and diagrams allowed where they genuinely clarify). Detects which platform hosts the repository — Gi
SKILL.md.claude/skills/iru-pr-description/SKILL.md
GitHubPR Description
Draft a pull request description from the real code changes, then either apply it to an existing PR or help open a new one. This skill never pushes, commits, or opens/edits a PR without the user explicitly confirming the specific action first.
Step 1 — Determine the repository host and available tooling
Before touching any PR, determine which platform hosts this repository, so the right tool is used throughout
instead of assuming GitHub/gh:
- If
iru-explorealready ran earlier in this conversation (e.g. this skill was invoked as part ofiru-issue, after its Step 5 exploration), reuse theRepository host: ...line from its Tech stack report rather than re-detecting. - Otherwise, detect it directly — the same way
iru-explore's own Step 2 does: get the remote URL (git remote get-url origin, falling back togit remote -vor whichever remote the current branch tracks) and match it against known patterns:github.com(or a GitHub Enterprise Server domain) → GitHub. Tooling: theghCLI, or GitHub MCP tools (ToolSearch"github").bitbucket.org(cloud), or a self-hosted domain with a/scm/<project>/<repo>.gitpath (Bitbucket Server/Data Center) → Bitbucket. Tooling: search for Bitbucket MCP tools first (ToolSearch"bitbucket"), otherwise the Bitbucket REST API.dev.azure.comor<org>.visualstudio.com→ Azure DevOps (cloud). Tooling:az repos(the Azure CLI with theazure-devopsextension) if installed, or Azure DevOps MCP tools (ToolSearch"azure devops").- A self-hosted domain with a
/tfs/path segment, or bare_gitin the path without adev.azure.com/visualstudio.comdomain → Azure DevOps Server / TFS. Same tooling family as Azure DevOps, but confirm the collection URL and API version before assuming parity. - If the URL doesn't clearly match any of these, ask the user (
AskUserQuestion) which platform it is rather than guessing.
- If there's no remote configured at all, tell the user a PR can't be inspected or created without a hosted remote, and stop — every step from here on assumes one exists (or will, once the branch is pushed).
Record the detected host — every later step's "use the host's tool" instruction refers back to this.
Step 2 — Determine the diff to describe, then delegate drafting
Determine the current branch:
git branch --show-current.Determine
<base-branch>— the branch this work forks from, which is both the range the diff is read against and the default destination for a new pull request in Step 6. Take the first of these that yields a branch, rather than deriving it from the repository's default branch straight away: when this skill runs as part of theiru-issuepipeline, the base was already resolved and confirmed with the user there, and re-deriving it here would silently describe (and target) a different base than the work was actually branched from.- An explicit
base-branch: <name>line in this skill'sargs— howiru-issue(Step 8) andiru-release(Step 14) hand over the base they already resolved. Authoritative: use it verbatim, don't re-derive. iru-issueran earlier in this conversation — reuse the<base-branch>it resolved and confirmed in its own Step 4.2, the same way Step 1 above reusesiru-explore's repository-host detection.- A
Base branch: <name>line in the plan's "Task summary" — readimplementation_plan.mdat the repository root, or, if it's already been archived by a finishediru-coderun, the most recent.archive/implementation_plan_*.md. This is what carries the choice across sessions, for the case where the user reviewed the plan manually and came back to run/iru-codeand/iru-pr-descriptionthemselves later. - Otherwise, derive it:
git symbolic-ref refs/remotes/origin/HEAD(strip therefs/remotes/origin/prefix), falling back tomain/masterif that ref isn't set, or asking the user if genuinely ambiguous. Note which of the four supplied the base — Step 7 reports it, so a wrong inherited value is visible rather than silently applied.
- An explicit
Check whether there's anything to describe at all, without reading the full diff yet:
git status,git diff --stat, andgit diff <base-branch>...HEAD --stat. If all three come back empty (no commits ahead of base, no staged/unstaged changes, no untracked files), tell the user and stop rather than inventing a description.Otherwise, delegate reading the full diff and drafting the description to a sub-agent, so the raw diff stays out of this conversation and only the drafted text comes back — nothing later in this skill needs the diff itself, only the draft:
Agent({ description: "Draft PR description from diff", prompt: "Read the full diff for this repository: commits already on the current branch (<current-branch>) but not on <base-branch> (git diff <base-branch>...HEAD), plus anything not yet committed (git status, git diff, git diff --staged), and recent commit messages for context on intent (git log --oneline against the same range). Draft a brief, concise pull request description grounded in what actually changed: one or two summary sentences, then a short bulleted list of the concrete changes if there is more than one logical change (omit any section that would be empty or redundant). Emojis are fine, used sparingly — one per bullet to categorize (✨ feature, 🐛 fix, ♻️ refactor, 📝 docs, ✅ tests) — don't overuse them. A small Mermaid diagram (a fenced ```mermaid block) is fine when a change reshapes control/data flow in a way a diagram clarifies faster than prose; skip it for straightforward changes regardless — most PRs don't need one. Don't invent behavior that isn't in the diff, and don't editorialize about code quality. Report back only the drafted description text — not the diff or commit log.", run_in_background: false })Reading a large diff directly into this conversation, when only the compact draft is ever used afterward, is the same class of waste
iru-gate-runner/iru-change-summarizeralready solve elsewhere in this catalog for other skills — a plain, unnamed sub-agent is enough here since this is a single, localized delegation rather than a shape repeated across several skills.
Step 3 — Check whether a pull request already exists
Use the tool matching the host detected in Step 1:
- GitHub:
If that returns nothing (e.g. the branch hasn't been pushed yet), also try:gh pr view --json number,title,url,baseRefName,headRefName,body 2>/dev/null
Ifgh pr list --head <branch> --json number,url,title,baseRefName,bodyghis unavailable/unauthenticated, search for GitHub MCP tools instead (ToolSearch"github pull request"). - Bitbucket: look up open pull requests via Bitbucket MCP tools if connected, otherwise the REST API (
GET /2.0/repositories/<workspace>/<repo>/pullrequests?q=source.branch.name="<branch>"for Cloud, or the Server/Data Center equivalent) — find the one whose source branch matches the current branch. - Azure DevOps / TFS:
az repos pr list --source-branch <branch> --status active, or Azure DevOps MCP tools if connected — find the one matching the current branch.
If no tool for the detected host is available at all (no CLI installed/authenticated and no matching MCP connection), tell the user and treat this as "no PR exists" — skip straight to Step 4, and in Step 6 only offer the printed description rather than attempting to create one.
Step 4 — Show the draft to the user
The description itself was already drafted by Step 2's sub-agent, grounded in the actual diff and recent commit messages. Before taking any further action: show it to the user as-is, and if the repository host is Bitbucket (from Step 1), strip or flag any Mermaid block first — GitHub and Azure DevOps render Mermaid natively in PR/ description bodies, Bitbucket does not.
Step 5 — Existing PR: offer to update it
If Step 3 found an existing PR:
- Show its number, URL, and current body next to the new draft.
- Ask the user whether to replace the PR's body with the draft.
- If yes: apply it with the tool matching the host detected in Step 1:
- GitHub: write the draft to a temp file and run
gh pr edit <number> --body-file <path>(a temp file avoids shell-quoting issues with multi-line/Markdown content). - Bitbucket: update the description via Bitbucket MCP tools if connected, otherwise a REST API call to the pull request's update endpoint with the new description field.
- Azure DevOps / TFS:
az repos pr update --id <number> --description "$(cat <path>)", or Azure DevOps MCP tools if connected. This edits shared, visible state — proceed only after the user's explicit yes.
- GitHub: write the draft to a temp file and run
- If no: stop — the draft has already been shown, there's nothing else to do.
Step 6 — No PR: offer to commit and open one
If Step 3 found no existing PR, ask the user (via AskUserQuestion) whether they want to commit the current
changes to a new branch and open a pull request now, or just keep the drafted description for manual use.
Creating branches, committing, pushing, and opening a PR are all visible and/or hard-to-reverse actions — never
do any of them without this explicit confirmation.
If they decline: stop — the draft from Step 4 is the deliverable.
If they accept, collect the specifics via AskUserQuestion, offering an inferred default for each so the user
can accept or override in one step:
- Branch name — default: when the work resolves a known GitHub issue or Jira ticket (a
Source:line in the plan's "Task summary" — the sameimplementation_plan.mdor archived copy Step 2 reads — or a ticket handled earlier in this conversation), follow the same conventioniru-issueuses:feature/<ticket-id>-<slug>orhotfix/<ticket-id>-<slug>, where<ticket-id>is the bare issue number or the Jira key (42,PROJ-123), the prefix ishotfixfor a bug fix andfeatureotherwise (judged from the ticket/draft), and<slug>is a short kebab-case summary of the ticket title (e.g.hotfix/PROJ-123-login-fails-after-session-timeout). With no ticket, a kebab-case slug derived from the draft's summary (e.g.fix-list-item-move-detection). If the current branch is already a non-default branch with commits ahead of base and no uncommitted changes, ask instead whether to reuse it rather than creating a new one — except when the current branch matchesclaude/*, the throwaway per-session branch of a Claude Code cloud/web run: say so and default to a new, properly named branch instead of offering to reuse it. - Destination branch — default:
<base-branch>as resolved in Step 2. Still ask (this step opens a PR), but pre-select that value rather than re-deriving the repository's default branch here. Never default to aclaude/*branch as a destination. - Pull request title — default: a concise, imperative one-liner derived from the draft.
Then, in order:
- If there are uncommitted changes, create the branch (
git checkout -b <branch-name>), stage the relevant files by name (avoidgit add -A/git add ., and check contents of anything unfamiliar before staging in case it holds secrets), and commit with a message consistent with this repo's recent style (git log --oneline -10for reference). If reusing the current branch per the note above, skip straight to step 2. - Push the branch:
git push -u origin <branch-name>. - Write the Step 4 draft to a temp file and open the PR with the tool matching the host detected in Step 1:
- GitHub:
gh pr create --base <destination-branch> --head <branch-name> --title "<title>" --body-file <path>. - Bitbucket: Bitbucket MCP tools if connected, otherwise
POST /2.0/repositories/<workspace>/<repo>/pullrequests(Cloud) or the Server/Data Center equivalent, with the title, the temp file's content as the description, the source branch, and the destination branch. - Azure DevOps / TFS:
az repos pr create --target-branch <destination-branch> --source-branch <branch-name> --title "<title>" --description "$(cat <path>)", or Azure DevOps MCP tools if connected.
- GitHub:
- Report the PR URL: the create command's own output for GitHub/Azure CLI; the API/MCP response's web link for
Bitbucket; or
az repos pr show --id <id> --query "_links.web.href" -o tsvfor Azure DevOps/TFS if the create step didn't already surface it.
Step 7 — Report
Summarize what happened: the drafted description, the <base-branch> used and which of Step 2's four sources it
came from (explicit args, an iru-issue run earlier in this conversation, the plan's Base branch: line, or
derived from the repository default), and the outcome — PR body updated (with URL), new PR created (with URL), or
description-only with no further action taken.