Menu
Use when generating or updating a PR description for the current branch. Takes an optional issue number as argument.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Stage B of /devflow-weekly: given the bundled context of every occurrence PR for one recurring pattern, re-derive the root cause, make the intervention edits in the working tree, and return the touched paths + PR title + PR body as JSON. Invoked as a subagent on a branch the orchestrator already created.
Run the weekly devflow self-improvement loop locally: scan freshly-merged watched-author PRs, write per-PR retrospective entries (LLM only for PRs that fail the mechanical clean-gate), derive recurring patterns, and open one human-reviewed intervention PR per actionable pattern. Use when running the weekly devflow retrospective + audit.
Use when setting up external documentation for the first time, performing a comprehensive documentation refresh, or when large portions of internal docs need corresponding external docs created.
Use when setting up internal documentation for the first time, when the docs directory is empty or poorly organized, or when a codebase has no structured developer documentation yet.
Use when a PR has customer-visible changes (new features, bug fixes, UI changes) that need a release note entry, or when finalizing a branch before merge.
Use when internal documentation has been updated and external customer-facing docs need to be aligned, or when checking for outdated, missing, or confidential content in external docs.
| name | pr-description |
| description | Use when generating or updating a PR description for the current branch. Takes an optional issue number as argument. |
| argument-hint | <issue-number> |
Generate a structured PR description by analyzing the current branch's changes against the base branch. When an existing PR is found, merges new content with human-added content instead of replacing it.
Input: $ARGUMENTS is an optional GitHub issue number. If provided, include a "Resolves #N" link.
Run these commands to understand what changed:
git fetch origin main
git log origin/main...HEAD --oneline
git diff origin/main...HEAD --stat
Read the diff details for any files that need deeper understanding:
git diff origin/main...HEAD
If an issue number was provided, fetch the issue for context:
gh issue view $ARGUMENTS --json title,body,labels
Check for an existing PR on the current branch:
gh pr view HEAD --json number,body,title 2>/dev/null
If this succeeds, an existing PR was found. Save the PR number and body for Step 2.
Best-effort: pull post-merge acceptance criteria from the /implement workpad. When /implement parses a related issue's Acceptance Criteria (its Phase 1.4), it tags items that can only be verified after merge with a trailing (post-merge) marker on the checkbox line. Surface those items in the PR body so the merger sees them and can tick them off after deploy.
If an issue number is available (from $ARGUMENTS or extracted from the existing PR body via (?i)(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+) — mirroring GitHub's own case-insensitive closes-keyword detection), look up the workpad and read its body:
ISSUE_NUMBER=$ARGUMENTS # or the extracted number
WORKPAD_ID=$(${CLAUDE_SKILL_DIR}/../../scripts/workpad.py id "$ISSUE_NUMBER" 2>/dev/null || true)
if [ -n "$WORKPAD_ID" ]; then
WORKPAD_BODY=$(${CLAUDE_SKILL_DIR}/../../scripts/workpad.py body "$WORKPAD_ID" 2>/dev/null || true)
fi
If WORKPAD_BODY is set, scan its ## Acceptance Criteria section for lines matching ^[-*]\s+\[[ x]\]\s+.*\(post-merge\)\s*$. Strip the leading checkbox and the trailing (post-merge) tag from each match; collect them as POST_MERGE_ITEMS for Step 2's template.
If no workpad exists, no issue number is available, or no (post-merge)-tagged items are found, POST_MERGE_ITEMS stays empty and the template's Post-Merge Verification section is omitted entirely. The lookup is best-effort — never fail the run on a missing workpad.
Best-effort: pull deferred review findings from the manifest. When /implement Phase 4.0.5 files follow-up issues for /devflow:review-and-fix deferrals, the manifest at .devflow/review/pr-<N>/deferrals.json is updated in place with id and follow_up fields per entry. Surface those entries in the PR body as a Scope-Acknowledged Findings block so /devflow:review (run later as a formal merge signal) can match them and demote the corresponding findings to Informational.
PR_NUMBER=$(gh pr view --json number --jq '.number' 2>/dev/null || true)
if [ -n "$PR_NUMBER" ]; then
DEFERRALS_FILE=".devflow/review/pr-${PR_NUMBER}/deferrals.json"
if [ -s "$DEFERRALS_FILE" ]; then
DEFERRALS_BODY=$(cat "$DEFERRALS_FILE")
fi
fi
If DEFERRALS_BODY is set and the parsed JSON has at least one entry under deferrals[] with a populated follow_up.issue, render the Deferred Findings section in Step 2's template (converting the JSON entries to the YAML shape shown there). Entries lacking a follow_up.issue are stale half-written manifests — skip them silently. Otherwise omit the section entirely. The lookup is best-effort — never fail the run on a missing or unparseable manifest.
Generate a fresh description using the template below.
Fetch the existing body and apply these merge rules:
Re-generate from the diff (always overwrite — these reflect current state):
POST_MERGE_ITEMS is non-empty — re-derived from the workpad on every run so the list stays in sync with the latest /implement parse)DEFERRALS_BODY is non-empty and contains entries with follow_up.issue — re-derived from the manifest on every run so the block stays in sync with the latest /implement Phase 4.0.5 filing)Merge (keep existing items that are still relevant, add new ones, remove stale ones):
Merge (combine existing and new):
$ARGUMENTS provides an issue number, include it; also keep any existing issue references that differ from $ARGUMENTSPreserve as-is:
<!-- PR_BODY_START --> or AFTER <!-- PR_BODY_END --> in the existing body — output it in the same position relative to the markersIf the existing body has NO markers: Treat the entire existing body as pre-marker content. Output it above <!-- PR_BODY_START -->, then generate the full template below the marker.
Output the description as plain text (not inside a code block) so it appears directly in your response:
[Group changes by module or concern. Use bold for the area name, colon, then a brief description.]
[Area name]: [What changed] [Area name]: [What changed]
Resolves #[issue number, or omit this section if no issue number was provided]
[Omit this entire section when POST_MERGE_ITEMS is empty. When non-empty, render as:] The following items can only be verified after this PR is merged or deployed. Tick each after performing the check.
[Omit this entire section when DEFERRALS_BODY is empty or contains no entries with a populated follow_up.issue. When non-empty, render with the markers — the /devflow:review verdict matcher parses them exactly:]
These review-agent findings were deferred under the Scope-Acknowledged Findings contract. /devflow:review honors matching entries as Informational; closing a linked follow-up issue invalidates the deferral and forces re-verification.
schema_version: 1
deferrals:
- id: <dfr-...>
finding:
agent: <agent>
severity: <Critical | Important | Suggestion>
file: <path>
line_range: [<start>, <end>]
symbol: <symbol or empty>
kind: <kind>
summary: |
<verbatim summary>
reason:
category: <out-of-scope | already-tracked | claim-quality>
explanation: |
<verbatim explanation>
follow_up:
issue: <N>
url: <url>
filed_at: <ISO 8601 UTC>
filed_by: <login>
[Describe UI changes, or "N/A" if none]
[Describe breaking changes and migration steps, or "None"]
Rules:
gh pr edit $PR_NUMBER --body "$(cat <<'EOF'
[full output including any pre/post-marker content]
EOF
)"