Back to Details

create-compelling-prs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

create-compelling-prs

打造有说服力的PR

Your PR competes for attention. The reviewer is looking at many PRs — if yours isn't immediately convincing, it gets skipped or rejected. Evidence beats rhetoric. A single well-implemented PR that convinces in 2 minutes is worth more than five that require follow-up.
你的PR需要争夺评审者的注意力。评审者要查看大量PR——如果你的PR不能立刻让人信服，就会被跳过或驳回。证据胜过空谈。一个能在2分钟内说服评审者的优质PR，价值远超五个需要后续跟进的PR。

PR Body Templates

PR正文模板

Pick the template matching your change type.
选择与你的变更类型匹配的模板。

Bugfix

Bug修复

markdown
undefined
markdown
undefined

What broke

问题描述

[One sentence: what failed and where]
[一句话说明：哪里出现了什么故障]

Root cause

根本原因

[The underlying cause — missing guard, race condition, wrong assumption]
[底层原因——缺失防护机制、竞态条件、错误假设]

Fix

修复方案

[What changed and why this approach over alternatives]
[做了哪些变更，以及为何选择此方案而非其他替代方案]

Before / After

前后对比

BeforeAfter
beforeafter
修复前修复后
beforeafter

Test output

测试输出

[paste test run]
[粘贴测试运行结果]

How to verify

验证步骤

  1. [Step to reproduce original bug — should now pass]
  2. [Regression check]
Closes #ISSUE
undefined
  1. [复现原bug的步骤——现在应能正常通过]
  2. [回归检查]
Closes #ISSUE
undefined

Feature

功能新增

markdown
undefined
markdown
undefined

What this adds

新增内容

[One sentence: the user-visible capability]
[一句话说明：用户可见的功能]

Why

背景原因

[Business or product motivation]
[业务或产品层面的动机]

Implementation

实现说明

[2-3 sentences: what was added/changed, key design decisions]
[2-3句话：新增/修改了什么，关键设计决策]

Demo

演示

demo
demo

Test output

测试输出

[paste test run]
[粘贴测试运行结果]

How to verify

验证步骤

  1. [Golden path step]
  2. [Edge case]
Closes #ISSUE
undefined
  1. [核心流程步骤]
  2. [边界情况测试]
Closes #ISSUE
undefined

Refactor

代码重构

markdown
undefined
markdown
undefined

What changed

变更内容

[What was moved, renamed, or restructured]
[哪些内容被移动、重命名或重构]

Why

重构原因

[The underlying problem that made this necessary]
[导致此次重构的潜在问题]

What stays the same

未变更内容

[Public API, behavior, outputs — nothing visible changed]
[公开API、行为、输出——无可见变化]

Test output

测试输出

[paste — proves no regressions]
Closes #ISSUE
undefined
[粘贴结果——证明无回归问题]
Closes #ISSUE
undefined

Deps

依赖更新

markdown
undefined
markdown
undefined

Update

更新内容

[Package] vX.Y.Z → vA.B.C
[包名] vX.Y.Z → vA.B.C

Why now

更新时机

[Security advisory / feature needed / routine bump]
[安全公告 / 需要新功能 / 例行升级]

Risk

风险等级

[Low/Medium/High — breaking changes? Coverage of affected areas?]
[低/中/高——是否有破坏性变更？受影响区域的测试覆盖情况？]

Test output

测试输出

[paste — full suite green]

---
[粘贴结果——全量测试通过]

---

Visual Evidence

可视化证据

For any UI-impacting change, capture before/after screenshots and embed them using the evidence-upload skill (
skills/ops/evidence-upload
).
bash
undefined
对于任何影响UI的变更，捕获前后截图并使用evidence-upload技能（
skills/ops/evidence-upload
）嵌入到PR中。
bash
undefined

Capture screenshots (Playwright preferred, manual fallback), then for each file:

捕获截图（优先使用Playwright，手动截图作为备选），然后对每个文件执行以下命令：

FILE=before.png CONTENT_TYPE=image/png REPO="$ORG/$REPO_NAME" BYTES=$(wc -c < "$FILE")
PRESIGN=$(curl -sS -X POST "$PYLOT_GATEWAY_URL/assets/presign"
-H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json"
-d "{"repo":"$REPO","content_type":"$CONTENT_TYPE","size":$BYTES}") ASSET_ID=$(echo "$PRESIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['asset_id'])") UPLOAD_URL=$(echo "$PRESIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_url'])")
curl -sS -X PUT "$UPLOAD_URL" --data-binary @"$FILE" -H "Content-Type: $CONTENT_TYPE"
PUBLIC_URL=$(curl -sS -X PATCH "$PYLOT_GATEWAY_URL/assets/$ASSET_ID"
-H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json"
-d '{"visibility":"public"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['public_url'])")
FILE=before.png CONTENT_TYPE=image/png REPO="$ORG/$REPO_NAME" BYTES=$(wc -c < "$FILE")
PRESIGN=$(curl -sS -X POST "$PYLOT_GATEWAY_URL/assets/presign"
-H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json"
-d "{"repo":"$REPO","content_type":"$CONTENT_TYPE","size":$BYTES}") ASSET_ID=$(echo "$PRESIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['asset_id'])") UPLOAD_URL=$(echo "$PRESIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_url'])")
curl -sS -X PUT "$UPLOAD_URL" --data-binary @"$FILE" -H "Content-Type: $CONTENT_TYPE"
PUBLIC_URL=$(curl -sS -X PATCH "$PYLOT_GATEWAY_URL/assets/$ASSET_ID"
-H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json"
-d '{"visibility":"public"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['public_url'])")

Embed: before

嵌入方式：before


`$PYLOT_GATEWAY_URL` and `$PYLOT_DISPATCH_TOKEN` are already in every operator/worker env. No AWS keys needed. See the evidence-upload skill for full error-handling and the allowlist (PNG/JPEG/GIF/WEBP/MP4, max 25 MB).

**Skip** if: backend-only, CLI-only, config/infra, test-only, or capture exceeds 120s. Visual evidence is a bonus, never a gate.

---

`$PYLOT_GATEWAY_URL` 和 `$PYLOT_DISPATCH_TOKEN` 已配置在所有操作员/工作环境中，无需AWS密钥。查看evidence-upload技能以获取完整的错误处理逻辑和允许列表（支持PNG/JPEG/GIF/WEBP/MP4格式，最大25 MB）。

**无需提供可视化证据的情况**：仅涉及后端、CLI、配置/基础设施、测试的变更，或捕获截图耗时超过120秒。可视化证据是加分项，绝非必要条件。

---

Self-Audit Checklist

自我审核清单

Run this before opening or marking a PR ready for review:
  • Complete? Does this finish every deliverable in the original task?
  • Shippable? If merged as-is, would the task be done — no follow-up tickets created?
  • No manual caveats? Zero "you'll need to X manually" instructions in the PR body.
  • Tests pass? Ran them yourself right now — not trusting earlier cached output.
  • Evidence present? Screenshots or test output embedded for every meaningful change.
  • Issue linked? 
    Closes #N
    in the body — or 
    Refs #N
    if the issue has unchecked acceptance criteria (prevents premature auto-close on multi-phase work).
If the "No manual caveats?" check fails: close the PR. File a blocker report instead. A PR that punts work back is worse than no PR. Reroute around obstacles — if the UI is the only path, use the API; if the API is missing, script it.
在提交PR或标记PR为待评审状态前，完成以下检查：
  • 是否完成？ 是否覆盖了原任务中的所有交付项？
  • 是否可发布？ 如果直接合并，任务是否完成——无需创建后续工单？
  • 无手动操作说明？ PR正文中没有任何“需要手动执行X操作”的说明。
  • 测试是否通过？ 你刚刚亲自运行了测试——而非依赖之前的缓存结果。
  • 是否提供证据？ 所有重要变更都嵌入了截图或测试输出。
  • 是否关联工单？ 正文中包含
    Closes #N
    ——如果工单有未完成的验收标准，则使用
    Refs #N
    （避免多阶段工作时提前自动关闭工单）。
如果“无手动操作说明？”未通过：关闭PR，转而提交阻塞问题报告。 将工作推给他人的PR比不提交更糟糕。要绕过障碍——如果只能通过UI操作，就使用API；如果API缺失，就编写脚本实现。

Lead Self-Assessment Loop

负责人自我评估流程

After a worker reports done, do not immediately accept. Press harder.
Iteration protocol:
  1. Ask: "What would you improve? How can you go the extra mile?"
  2. Require actions, not claims — "I'd add tests" → demand they write them now. "I'd verify it renders" → demand a screenshot.
  3. When improvement is done, ask again.
  4. Stop after ~3 iterations if returns are marginal. After 10 with persistent gaps → respawn with stricter instructions.
Rules:
  • Never accept rhetoric. "I'm confident this is solid" is not evidence — demand it.
  • Verify independently. Run the tests yourself. Open the PR URL. Load the live site.
  • Track the diff between iterations. No file changes = worker is stalling → push harder.
Rotation questions (vary to avoid formulaic answers):
  • "What would a senior engineer reject in code review?"
  • "Run the full test suite now and paste the output."
  • "Screenshot the affected page. Does it match the design system?"
  • "What did you punt on? Re-read the task and list every deliverable."
  • "If this gets rejected, what's the most likely reason? Fix it preemptively."
当工作人员报告任务完成后，不要立即接受，需进一步确认。
迭代流程：
  1. 询问：“你会做哪些改进？如何更进一步？”
  2. 要求提供具体行动，而非口头承诺——比如“我会添加测试”→要求立即编写测试；“我会验证渲染效果”→要求提供截图。
  3. 当改进完成后，再次询问相同问题。
  4. 如果经过约3次迭代后收益甚微，则停止。如果经过10次迭代仍存在持续差距→重新分配任务并给出更严格的要求。
规则：
  • 绝不接受空谈。 “我确信这没问题”不是证据——要求提供实际证据。
  • 独立验证。 亲自运行测试，打开PR链接，加载线上站点。
  • 追踪迭代间的差异。 若无文件变更→工作人员在拖延→进一步施压。
轮换问题（避免千篇一律的回答）：
  • “资深工程师在代码评审中会驳回哪些内容？”
  • “立即运行全量测试套件并粘贴输出结果。”
  • “截图受影响的页面，是否符合设计系统规范？”
  • “你跳过了哪些工作？重新阅读任务并列出所有交付项。”
  • “如果这个PR被驳回，最可能的原因是什么？提前修复它。”