SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillspr

pr

General & other

View repository

Updated 10-15 19:58

About this skill

/pr — Summarize work and maintain PR

Please execute the following steps:

Step 1: Analyze the current work

1a. Git analysis

  1. Run git status and git diff(staged + unstaged) to understanduncommitted changes
  2. Run git log to check recent commit style
  3. Key step — sync the remote and confirm the full scope of the PR:
    • First run git fetch origin(⚠️ Stale Local Branch trap: the local master/main/hotfix may be dozens of commits behind the remote; forgetting to fetch will count already merged commits into the PR scope, causing the description to be severely inaccurate)
    • Run git log --oneline origin/<base-branch>..HEAD to view theall commits(always compare with origin/<base-branch> , do not use the local <base-branch>）
    • run gh pr diff <PR-number> --name-only to view theall files
    • If an open PR already exists, run gh pr view <PR-number> --json body to read the existing description
    • Cross-validate: compare the git log result with the gh pr diff result; if the difference is too large (for example, git log shows 50+ commits but gh pr diff shows only 1-2 files), use gh pr diff as authoritative and re-examine

1b. Conversation context analysis

Review the complete content of this conversation, and extract the following context items (this list is the only authoritative list for this skill; when writing the PR description in Step 5, compare item by item and do not redefine them):

  1. Motivation: What problem or requirement did the user initially raise?
  2. Discussion process: Which approaches were explored during the process? What comparisons or investigations were made?
  3. Decision points: Where were there multiple choices? Why was this approach ultimately chosen?
  4. Abandoned attempts: Were there any approaches that were tried but abandoned? Why were they abandoned?
  5. Implicit knowledge: important context that appeared in the conversation but will not be reflected in the diff (for example: investigation data, external tool comparisons, performance considerations)
  6. Industry/academic basis: Did the technical decisions cite industry standards (RFC, OWASP, etc.) or academic research?
  7. Community consensus and opposing opinions: Were mainstream community views, known opposing opinions, or pitfalls discussed in the conversation?
  8. Ticket reference: Scan the conversation for [A-Z]+-\d+ numbers (such as JIRA-123), Notion URLs, or the words "Notion Ticket", and record the numbers and ticket names found (for use in the Step 5 PR title)
    • PDT ticket (Linear, mandatory): Also scan these four sources for PDT-\d+(case-insensitive): conversation content, current branch name (git branch --show-current, such as fix/pdt-11061-...）、origin/<base-branch>..HEAD commit messages, and the title/body of an existing PR. Once matched, always normalize to uppercase PDT-<number>, record it only here and do not duplicate it in the general ticket list above; record it in the Context Manifest and pass it down to Step 3.5 (branch naming) and Step 5 (PR title). If there are multiple, list them all
    • Only count the ticket corresponding to this work: for example, citations, references to other PR titles,blocked by/ related tickets and similar incidental mention numbers do not count. If multiple numbers appear in the conversation and it is impossible to tell which one is the work for this task, use AskUserQuestion to let the user choose; do not guess

⚠️ Common mistakes: looking only at git diff will miss the contents of other commits in the PR; looking only at the diff without looking at the conversation will miss the decision context of "why it was done this way". The PR description must reflect both what changed（diff） and why it changed (conversation context)。

Create a "Context Manifest" at the end of Step 1b, for Step 5 to compare item by item:

## Context Manifest（Step 1b → Step 5 交接）

| # | Context 類型 | 摘要 | 已寫入 PR Description？ |
|---|------------|------|------------------------|
| 1 | 動機 | 使用者原始需求 xxx | 待比對 |
| 2 | 放棄的方案 | 考慮過 A 但因 B 放棄 | 待比對 |
| 3 | 決策依據 | 選 X 不選 Y，因為 Z | 待比對 |
| ... | ... | ... | 待比對 |

expected_count = N（對話中識別的 context 項目總數）

1c. Summary

Combine git analysis + conversation context to summarize this work'spurpose, what was done, and why it was done this way。

Step 2: Quick Review

Perform a quick code review of all changes, checking the following items:

Checklist

  • Security: whether sensitive information is leaked (API keys, secrets, .env contents)
  • Correctness: whether the logic is correct and there are no obvious bugs
  • Leftovers: whether debug code (console.log, debugger) remains uncleared
  • Types: whether TypeScript types are correct and whether there is any abuse
  • Style: whether it conforms to the project's existing coding style
  • Visual acceptance aspect: does the change touch UI visuals/interactive behavior? If it does, list a draft of "items pending screenshot acceptance" (one assertion per item that can be judged PASS/FAIL) and hand it to Step 5.5 for finalization; if it does not, explicitly state "no visual aspect, Step 5.5 will be skipped"

Proactive security review (according to rules/security-guidance/skill-integration.md 's trigger gate)

Determine whether the change touches security-sensitive aspects (auth/input/endpoint/DB/deserialization/file/shell/SSRF/DOM/crypto, definitions as in the above document):

  • Touches → delegate to the built-in /security-review skill to review the pending changes of the current branch, with criteria based on ~/.claude/claude-security-guidance.md ; findings are merged into the output below, and CRITICAL/HIGH are flagged in "Interactive confirmation" to be fixed first
  • Does not touch → explicitly state "no security-sensitive aspect, skipped"
  • If chained from /update :: Step 2 already includes security review, so do not delegate again here (deduplicate). However, **the "visual acceptance aspect" determination is not within /update 's scope**—even if the rest of this step's checks are skipped, that determination must still be made (or Step 5.5a directly supplements the determination from gh pr diff --name-only ), otherwise Step 5.5 will have no input and be mistakenly skipped

Output format

Present the review results with a concise table or list:

  • ✅ Items with no issues are mentioned in one sentence
  • ⚠️ Items with concerns but non-blocking explain the reason
  • ❌ Problems that must be fixed list the file and line number

Interactive confirmation

After the review is complete, use AskUserQuestion to ask the user:

  • Continue the PR process: the review results have no issues, continue commit → push → PR
  • Fix issues first: handle the issues found in review first, then re-run after fixing /pr

If the user chooses "Fix issues first", fix them one by one according to the review results, and after fixing, start again from Step 1.

Step 2b: Auto-fix

If Step 2 finds issues that can be auto-fixed (dead code, naming, nesting, duplicate code), delegate to the built-in /simplify skill to execute; if none are found, skip.

Step 2c: Plan archiving check

Before committing, if the plan involved in this conversation is already complete (plans/active/*.md 's Status is COMPLETED/完成, or all Phase/Step are marked [x]/✅), call the /plan-archive skill to archive to plans/completed/; if there is no completed plan, skip.

Step 3: Commit current changes

  1. If there are uncommitted changes, write a commit message based on the changes
  2. Use the conventional commits format (feat / fix / chore / refactor / test / docs), write in English
  3. Make sure not to commit sensitive files (.env, credentials, etc.)

Step 3.5: PDT ticket and branch name (only do this if a PDT was found in Step 1b)

The branch name must include the ticket, format <type>/pdt-<number>-<kebab-slug>(e.g.:fix/pdt-11061-editor-toolbar-keyboard-sticky），<type> follows the conventional commit prefix. If no PDT is found, skip this step.

Current state Action
Branch name already contains pdt-<number>(case-insensitive) Matches, go directly to Step 4
Still on a base/long-lived branch (main、master、hotfix、develop*、release-*） Create a new branch directly using the format above, do not change the name of the long-lived branch
Own branch,not yet pushed to remote and no PR Use AskUserQuestion to propose git branch -m <新名>, options "Rename (recommended)" / "Keep original name"
Already pushed to remote or PR exists Do not rename(re-pushing under a new name would break the existing PR), the ticket is then carried by the PR title, and note in the Step 6 report that the branch name does not include the ticket

Step 4: Push to remote

If there is a remote tracking branch, use git push; if not, git push -u origin <branch> to create it.

Step 5: Create or update PR

Base Branch protection (enforced)

The PR's base branch is forbidden from pointing directly at the main production branch (such as master、main）。

Perform the following checks:

  1. Read the project's branch strategy (if there is a skills/git-workflow/SKILL.md or similar file)
  2. If the project defines a default base branch (such as hotfix、develop), automatically use that branch
  3. If the user explicitly requests pointing to master or main → must interrupt and warn：
    • Use AskUserQuestion to remind: "According to project conventions, PRs are not recommended to point directly at master/main. Are you sure you want to continue?"
    • Provide options: "Change to [project default base branch] (recommended)" / "I am sure I want to point to master/main"
    • Only continue after the user explicitly confirms
  4. If the project has no special branch strategy, use the repo's default branch
# 範例：專案規範 base branch 為 hotfix
gh pr create --base hotfix ...

# 禁止（除非使用者明確確認）
gh pr create --base master ...

CHANGELOG check (for Release PR only)

When the base branch is master or main ,MustCheck CHANGELOG.md:

  1. Confirm whether the project root has CHANGELOG.md
  2. If so, check whether the latest entry covers the changes in this PR:
    • Read the latest version section of CHANGELOG.md
    • Compare git log origin/<base-branch>..HEAD --oneline 's commits
    • If there are commits not recorded in the CHANGELOG → use AskUserQuestion to remind:

      CHANGELOG.md does not yet include the following changes:

      • <未記錄的 commit 摘要>

      1. Help me update the CHANGELOG — automatically add the missing entries
      2. Skip — do not update the CHANGELOG, continue the PR process
  3. If the project does not have a CHANGELOG.md, skip this step

PR Title format

Determine the PR title based on the base branch and ticket reference:

Release PR (base branch is master/main)

When the PR's base branch is master or main , the titlemustuse the Release format:

  • Format:Release vX.Y.Z: <摘要>
  • Example:Release v1.18.0: add skill defer + CHANGELOG updates
  • Version number inference priority: CHANGELOG.md latest version → package.json version → git tag
  • For the summary, extract the main changes from the commits included in the PR; a brief description is sufficient
  • If a PDT ticket is found in Step 1b, append all numbers to the end of the title:Release v1.18.0: <摘要> (PDT-10980 PDT-10779)

When updating an existing PR, you must also check whether the title complies with this rule; if it does not, update it as well.

General PR (base branch is not master/main)

Use the ticket reference extracted in Step 1b to determine the PR title:

  • A PDT ticket was found → the titlemustinclude the literal PDT-<number>, simply writing the ticket name does not count. By default, place it at the end:fix(kyc): 注意事項清單改 inline style (PDT-10908). If the repo convention is to put it in the scope (fix(PDT-11061): ...), that is also acceptable. List all tickets:(PDT-10980 PDT-10779)
  • Other tickets were found(excluding PDT; for PDT always follow the previous item) → the title must include ticket information, choose one of the two:
    1. Append the ticket number at the end of the title:fix(seo): add noindex for empty about page (TICKET-1234)
    2. The title includes the ticket name:fix(seo): [Bug] empty about page should be no-indexed
  • No ticket was found → normal title, no extra handling needed

When updating an existing PR, also check whether the title is missing the PDT number; if it is missing, use gh pr edit --title to add it.

Decision logic

  • If a PR number is provided ($ARGUMENTS), update that PR
  • If no number is provided, check whether the current branch already has an open PR
    • Yes → update that PR description
    • No → create a new PR (use the base branch specified by the project conventions)

PR Description format

The PR description must include the following sections, written in Traditional Chinese:

## Summary

<!-- 1-3 句話說明這個 PR 的目的和背景脈絡，讓 reviewer 30 秒內理解「為什麼要做這件事」 -->

## Context（對話脈絡）

<!-- 最重要的區塊。內容依 Step 1b 的 Context Manifest 逐條寫入，來源優先序：對話脈絡 > git diff > commit messages -->
<!-- 目標：reviewer 不需要問「為什麼這樣做？」就能從這裡找到答案 -->

## Changes

<!-- 按主題分類列出變更，涵蓋 PR 的所有 commits（不只是當次對話的工作） -->
<!-- 用 git log origin/<base-branch>..HEAD 確認完整範圍（必須先 git fetch origin） -->
<!-- 用 git diff origin/<base-branch>..HEAD --diff-filter=D --name-only 確認刪除的檔案 -->
<!-- 本次對話沒親自做過的 commit（跨 session 累積的 branch、更新既有 PR）：其條目的
     「改了什麼」必須對 git diff 核實，commit message 只用來定位該查哪段 diff，不能當證據；
     核不到佐證的標「無法佐證」列出來，不要為了讓 body 看起來完整而放寬。
     當次對話親自做的照舊（diff 就在對話裡，不必重查）。 -->
<!-- 每個主題明確標示：新增了什麼、刪除了什麼、修改了什麼 -->

## Test plan

<!-- 測試計畫，checkbox 格式 -->
<!-- 若 Step 2 判定有視覺面，此處列出待截圖驗收的編號項目（B1/C1…），並在 Step 5.5 完成後回頭勾選；
     移除／重構類不要列截圖項，改列量測項（grep 殘留、bundle diff、目錄不存在） -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Manifest item-by-item comparison: After writing the Context section, compare item by item against the Context Manifest from Step 1b to ensure every item has been reflected; items with a difference (expected_count − actual_written) > 0 must be filled in and must not be omitted.

Evidence Gate (mandatory before writing back)

After the description is finalized, before executing gh pr create/gh pr edit , call the evidence-gate skill to pass the gate: the commit range is fixed to origin/<base-branch>..HEAD(continuing from the scope already git fetch origin in Step 1a), split each factual claim in the description into the Claim Schema in Section 1 of that skill, and always trace evidence back to git diff/git log --numstat; the commit message is only for locating, not for serving as evidence; and per Section 4 of that skill, dispatch a fresh-context subagent for adversarial re-verification. Only when there are zero FAILs and zero SCHEMA-DEFECTs may you continue to the gh pr create/gh pr editbelow; if there is any FAIL or SCHEMA-DEFECT, return to this section to fix the description, and do not write it back to the PR.

Skill({ skill: "evidence-gate" })

Step 5.5: Screenshot acceptance gate (run after the PR already exists)

After the PR is created/updated, determine whether this changerequires screenshot acceptance, and if so, use AskUserQuestion to obtain authorization before running it. This step is done only after Step 5: screenshots must be posted as PR comments, and if the PR (and preview env) does not exist, there is nowhere to put them.

The scope of applicability is not limited to PRs created by /pr . If the PR was created by a dispatch agent or manually via gh pr create , the dispatcher must still run this step after the PR exists—what is delegated is the work, not the responsibility. This gate is written only in /pr , so paths that bypass /pr will make it silently disappear; and "asking an agent to open a PR" is precisely the most common way to bypass it.

One state to especially catch:the screenshots have already been taken and the trace has been saved, but everything ends up in a local path such as .verification/ .The evidence exists but is stuck somewhere the reviewer cannot open it, which is equivalent to having no evidence—this is precisely the problem that /pr-evidence-comment is meant to solve.

5.5a Classification (reusing /pr-evidence-comment the same table from Step 0)

Classify based on the "visual acceptance surface" determination from Step 2 and gh pr diff <PR> --name-only :

Change type Acceptance method Action in this step
UI visuals/interactive behavior headed screenshot Proceed to 5.5b to ask
"Behavior unchanged" after state migration Screenshot (prove it is not broken) + measurement (prove it really migrated) Proceed to 5.5b to ask, and remind that the measurement items cannot be omitted
Pure removal/refactor Measurement (grep for leftovers, bundle diff, directory does not exist) Do not ask about screenshots, directly prompt to add measurement items to the Test plan
API/data correctness curl/test output Do not ask about screenshots, directly prompt to add test output
Pure docs/config/CI None Explicitly state "no visual surface, skip"

Removal-type changes cannot be captured: a screenshot can only show "it looks normal," not prove "the thing is really gone." Do not chase screenshots just to have an image.

5.5b Interactive confirmation (AskUserQuestion)

When it is determined that "screenshot acceptance is required,"you mustuse AskUserQuestion to ask; you may not decide on your own whether to run it or not (it will open a browser, require manual login, and publicly post a comment as the user).

Include in the question: the detected visual-surface changed files, the numbered list of acceptance items drafted in Step 2, and the available acceptance environments (preview URL/staging/local). Options:

  1. Verify now (recommended) — delegate to /pr-evidence-comment, passing in the acceptance checklist and environment URL
  2. Just list the checklist, I'll verify myself — write the numbered checklist into the PR's Test plan (unchecked), without opening a browser
  3. Not needed this time — record the reason and add a line in the PR explaining why visual acceptance is waived

Environment determination: when base is the project's default branch and the repo has a preview deployment convention, first confirm whether the preview env is ready (e.g. the PR needs a specific label to deploy).If not ready, don't force it— instead ask the user whether to "wait for preview to be ready before verifying" or "verify with local first".

5.5c Execution and backfill

User chooses 1 → delegate using the Skill tool:

Skill({ skill: "pr-evidence-comment" })

After that skill finishes (screenshots uploaded,gh pr view verified that the user-attachments count matches), return to this step:

  • Backfill the item-by-item PASS/FAIL conclusions into the PR description's Test plan (check off verified items)
  • FAIL itemsmust notbe glossed over as "accepted" — list them and return to the fix flow
  • Also post the acceptance conclusions back as a PR comment (done by that skill); only summarize in the conversation
  • For this backfill,no need to rerun Step 5's evidence-gate: the evidence is the screenshots and comment link just generated; reference them directly when backfilling; but the Test plan may only list items actually verified, and unverified ones stay unchecked

User chooses 2 or 3 → write back to the Test plan/explanation according to the option, without calling that skill.

Step 6: Confirm the result

  1. Output the PR URL
  2. Confirm the PR description has been updated
  3. Report the result of Step 5.5: screenshots taken for acceptance (with comment link) / checklist listed pending manual verification / determined exempt from verification (with reason) / no visual aspect
  4. Report where the PDT ticket is placed: the detected number and its source, whether the PR title includes it, whether the branch name includes it. If not included, state the reason (e.g. the branch is already pushed to remote, so it won't be renamed). If no PDT is found, explicitly say "no PDT ticket detected"
  5. If there are other related PRs (e.g. feature → develop, develop → master), check whether they need to be updated in sync

Usage

/pr # automatically detect whether there is an open PR; if not, create a new one /pr 7195 # update the description of the specified PR