pr-polish

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/pr-polish

Holistic quality elevation for a PR that already works.

为已能正常运行的PR提供全方位的质量提升。

Role

角色

Staff engineer doing a retrospective pass. Not finding bugs — asking "would we build it the same way starting over?"

资深工程师进行回顾性审查。并非寻找bug，而是思考“如果重新开始，我们是否会用同样的方式构建它？”

Objective

目标

Elevate PR

$ARGUMENTS

(or current branch's PR) from "works" to "exemplary": clean architecture, solid tests, current docs.

将PR

$ARGUMENTS

（或当前分支对应的PR）从“可用”提升至“典范”级别：架构清晰、测试可靠、文档最新。

Precondition Gate

前置检查门禁

Before starting, verify:

bash

gh pr view $PR --json mergeable,statusCheckRollup,reviewDecision

Requirements:

No merge conflicts
CI green
No unaddressed critical review feedback

If any fail: Tell user to run

/pr-fix

first. Do not proceed.

开始前，先验证以下内容：

bash

gh pr view $PR --json mergeable,statusCheckRollup,reviewDecision

要求：

无合并冲突
CI检查通过
无未处理的关键评审反馈

若任意检查不通过：告知用户先运行

/pr-fix

，不继续执行后续步骤。

Workflow

工作流程

1. Context

1. 收集上下文

Read everything about this PR:

bash

gh pr view $PR --json body,commits,files
gh pr diff $PR

Read linked issue(s). Read commit history. Understand the full arc of what was built and why.

阅读与该PR相关的所有内容：

bash

gh pr view $PR --json body,commits,files
gh pr diff $PR

阅读关联的Issue、提交历史，全面理解功能的构建过程及设计初衷。

2. Hindsight Review

2. 事后回顾（Hindsight Review）

Launch

hindsight-reviewer

agent via Task tool.

Key question: "Knowing what we know now — the final shape of the code, the edge cases discovered, the patterns that emerged — would you build it the same way?"

Feed it: full diff against main, PR description, linked issue.

Expect back: architectural observations, naming concerns, abstraction boundaries, missed simplifications.

通过Task工具启动

hindsight-reviewer

agent。

核心问题：“基于当前已掌握的所有信息——包括代码的最终形态、发现的边缘情况、形成的设计模式——如果重新开始，你会用同样的方式构建它吗？”

提供给agent的信息：与主分支的完整差异、PR描述、关联Issue。

预期输出：架构层面的观察结论、命名问题、抽象边界问题、遗漏的简化点。

3. Refactor

3. 重构

Invoke

/refactor

for findings that are addressable now:

Naming improvements
Shallow module consolidation
Unnecessary abstraction removal
Code path simplification

For architectural findings that require broader changes: create GitHub issues.

bash

gh issue create --title "[Arch] Finding from PR #$PR hindsight review" --body "..."

针对可立即处理的回顾结论，调用

/refactor

：

命名优化
浅层模块合并
移除不必要的抽象
简化代码路径

对于需要大范围调整的架构问题：创建GitHub Issue。

bash

gh issue create --title "[Arch] PR #$PR 事后回顾发现的问题" --body "..."

3.5. Simplify

3.5. 简化

Invoke

/simplify

on the PR's changed files.

The code-simplifier agent reviews recently modified code for clarity, consistency, and maintainability — complementing the architectural lens of hindsight review with line-level refinement:

Reduce unnecessary complexity and nesting
Eliminate redundant abstractions
Improve naming clarity
Consolidate related logic
Remove obvious comments

This catches things the refactor step doesn't: verbose patterns, inconsistent style, overly compact one-liners, nested ternaries.

对PR中修改的文件调用

/simplify

。

代码简化agent会从代码清晰度、一致性、可维护性角度审查最近修改的代码——与事后回顾的架构层面分析形成互补，聚焦于代码行级别的优化：

减少不必要的复杂度和嵌套
消除冗余抽象
提升命名清晰度
合并相关逻辑
移除多余注释

这一步能捕捉到重构步骤未覆盖的问题：冗余模式、风格不一致、过度紧凑的单行代码、嵌套三元表达式等。

4. Test Audit

4. 测试审计

Review test coverage for the PR's changed files. Look for:

Missing edge cases
Error path coverage
Behavior tests (not implementation tests — per
```
/testing-philosophy
```
)
Boundary conditions
Integration gaps

Write missing tests. Each test should justify its existence — no coverage-padding.

审查PR修改文件的测试覆盖率，重点关注：

遗漏的边缘情况
错误路径覆盖
行为测试（而非实现测试——遵循
```
/testing-philosophy
```
）
边界条件
集成间隙

补充缺失的测试。每个测试都需明确存在的意义——不为了覆盖率而凑数。

5. Documentation

5. 文档完善

Invoke

/update-docs

for anything the PR affects:

ADRs for architectural decisions made during implementation
README updates for new features or changed behavior
Architecture diagrams if module boundaries changed
API docs if endpoints changed

针对PR影响到的所有内容，调用

/update-docs

：

实现过程中架构决策的ADR文档
新功能或行为变更的README更新
模块边界变更时的架构图
接口变更时的API文档

6. Quality Gates

6. 质量门禁

Invoke

/check-quality

and run project verification:

bash

pnpm typecheck && pnpm lint && pnpm test

All gates must pass. Fix anything that doesn't.

调用

/check-quality

并运行项目验证：

bash

pnpm typecheck && pnpm lint && pnpm test

所有门禁必须通过。修复未通过的内容。

7. Update PR Description with Before / After

7. 为PR描述添加“前后对比”部分

Edit the PR body to include (or update) a Before / After section documenting the polish pass:

bash

gh pr edit $PR --body "$(current body + before/after section)"

Text (MANDATORY): Describe the state before polish (e.g., "working but with shallow modules and missing edge-case tests") and after (e.g., "consolidated modules, 12 new edge-case tests, updated architecture docs").

Screenshots (when applicable): Capture before/after for any visible change — refactored UI output, improved error messages, updated docs pages. Use

![before](url)

![after](url)

Skip screenshots only when all polish was purely internal (refactoring with no visible output change).

编辑PR正文，添加（或更新）“前后对比”章节，记录本次优化过程：

bash

gh pr edit $PR --body "$(当前正文 + 前后对比章节)"

必填内容：描述优化前的状态（例如：“可正常运行，但存在浅层模块和遗漏的边缘情况测试”）和优化后的状态（例如：“已合并模块、新增12个边缘情况测试、更新了架构文档”）。

截图（适用时）：对所有可见变更截取前后对比图——重构后的UI输出、优化后的错误提示、更新后的文档页面。使用

![before](url)

![after](url)

格式。

仅当所有优化均为内部变更（重构未带来可见输出变化）时，可跳过截图。

7.5 Diagram Audit

7.5. 图表审计

Check PR body for visual communication:

bash

gh pr view $PR --json body | jq -r '.body'

Does the PR body have a
```
## What Changed
```
Mermaid diagram?
If no, and the change involves logic/architecture/data flow: generate one using
```
~/.claude/skills/visualize/references/github-mermaid-patterns.md
```
If yes: validate it accurately reflects the final state (diagrams drift during review)
Add or update diagram in PR body:
```
gh pr edit $PR --body "$(updated body)"
```

Omit only when the change is purely internal with no branching or relationships.

检查PR正文中的可视化内容：

bash

gh pr view $PR --json body | jq -r '.body'

PR正文中是否包含
```
## What Changed
```
章节的Mermaid图表？
若没有，且变更涉及逻辑/架构/数据流：使用
```
~/.claude/skills/visualize/references/github-mermaid-patterns.md
```
生成图表
若已有图表：验证其是否准确反映最终状态（图表可能在评审过程中过时）

在PR正文中添加或更新图表：

gh pr edit $PR --body "$(更新后的正文)"

仅当变更为纯内部调整且无分支或关系变化时，可省略此步骤。

8. Refresh Glance Summaries (Conditional)

8. 更新Glance摘要（可选）

If this PR added, removed, or significantly restructured directories:

bash

glance   # run from repo root — skips up-to-date directories automatically

Do NOT pass

-force

. Glance handles intelligent regeneration based on existing

.glance.md

files. Only affects directories that changed.

Commit any updated

.glance.md

files with the PR branch.

若PR添加、移除或大幅重构了目录结构：

bash

glance   # 从仓库根目录运行——自动跳过已更新的目录

请勿使用

-force

参数。Glance会基于现有

.glance.md

文件智能生成更新内容。仅影响发生变更的目录。

将更新后的

.glance.md

文件提交至PR分支。

9. Codify (Optional)

9. 固化知识（可选）

If patterns or learnings emerged during this polish pass, invoke

/distill

to capture them as permanent knowledge (hooks, agents, skills, CLAUDE.md entries).

Skip if nothing novel surfaced.

若本次优化过程中形成了可复用的模式或经验，调用

/distill

将其转化为永久知识（钩子、agent、技能、CLAUDE.md条目）。

若未产生新的经验，可跳过此步骤。

Agent Teams Mode

Agent团队模式

For large PRs (>500 line diff), parallelize phases 3-5:

Teammate	Task
Refactorer	`/refactor` on hindsight findings
Simplifier	`/simplify` on changed files
Test writer	Test audit + write missing tests
Doc updater	`/update-docs`

Lead sequences: hindsight first (all teammates need its output), then parallel work, then quality gates.

对于大型PR（差异代码超过500行），可并行执行步骤3-5：

团队成员	任务
重构专员	针对事后回顾发现的问题执行 `/refactor`
简化专员	对修改的文件执行 `/simplify`
测试编写者	测试审计 + 补充缺失的测试
文档更新者	执行 `/update-docs`

执行顺序：先完成事后回顾（所有团队成员都需要其输出），再并行执行各任务，最后进行质量门禁检查。

Anti-Patterns

反模式

Polishing a PR that doesn't work yet (use
```
/pr-fix
```
first)
Architectural refactors in a polish pass (create issues instead)
Adding tests for coverage percentage instead of confidence
Documenting obvious mechanics instead of non-obvious decisions
Skipping hindsight and jumping straight to refactoring

对尚未可用的PR进行优化（应先使用
```
/pr-fix
```
）
在优化步骤中进行架构重构（应改为创建Issue）
为了覆盖率百分比而非信心添加测试
记录显而易见的实现细节而非非直观的决策
跳过事后回顾直接进行重构

Output

输出

Summary: hindsight findings, refactors applied, issues created, tests added, docs updated, quality gate results, learnings codified.

总结内容：事后回顾发现的问题、已应用的重构、创建的Issue、新增的测试、更新的文档、质量门禁结果、固化的经验。