interface-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Review the change, not just the code it left behind

审查变更,而非仅审查遗留代码

A diff is not a surface. The lines a change deletes matter as much as the lines it adds, and the file it touches is rarely the whole of what it affects.
This skill owns change scope only: resolving the target, expanding changed files to affected surfaces, reading both sides of the diff, and classifying each finding. Domain rules belong to the six
better-*
skills. Mode, severity, consolidation, coverage, the cap, the output format, and the verdict belong to
better-interface
, which this skill hands the review to. Never duplicate or override their rules here.
Correctness, tests, security, and performance belong to the project's general code review. Name the concern once and move on.
差异(diff)并非界面本身。变更删除的代码行与新增的代码行同等重要,且变更涉及的文件很少是其影响的全部范围。
本技能仅负责变更范围的处理:确定审查目标,将变更文件扩展至受影响的界面,读取差异的双方内容,并对每个发现进行分类。领域规则由六个
better-*
技能负责。审查模式、严重性、合并规则、覆盖范围、上限、输出格式及最终结论由
better-interface
负责,本技能会将审查结果移交至该技能。请勿在此处重复或覆盖其规则。
正确性、测试、安全性和性能属于项目通用代码审查的范畴。只需提及一次相关问题即可,无需深入。

Quick Reference

快速参考

CategoryWhen to Use
Scope ResolutionTargets and commands, default branch, merge-base, PR and fork refs, repository states, renames, exclusions, consumer expansion
Removed SignalsWhat to look for on the
-
side of a hunk and which skill owns each removal
分类使用场景
范围解析审查目标与指令、默认分支、合并基准(merge-base)、拉取请求(PR)与分支引用、仓库状态、文件重命名、排除项、消费者扩展
移除信号需在代码块的
-
侧查找的内容,以及每个移除项对应的负责技能

Core Principles

核心原则

1. Resolve the Change Scope First

1. 先确定变更范围

better-interface
owns mode parsing; everything after the mode is the target, so
/interface-review quick pr 482
is a
quick
review of pull request 482. Scope Resolution holds the accepted targets and the command for each.
With no target supplied, resolve in this order and stop at the first match:
  1. HEAD
    is ahead of
    git merge-base origin/<default-branch> HEAD
    : that range plus any uncommitted changes, with the commit count and uncommitted file count stated separately.
  2. The working tree is dirty: the uncommitted changes.
  3. Otherwise,
    HEAD~1..HEAD
    , stated as a fallback.
Order matters: checking the working tree first lets one stray formatting edit shadow a twelve-commit branch while the report still claims full coverage.
Exclude lockfiles, snapshots, generated output, vendored code, and binaries, and name what you excluded. If the scope is empty after exclusions, say so and stop.
better-interface
负责解析审查模式;模式之后的所有内容即为审查目标,因此
/interface-review quick pr 482
表示对第482号拉取请求进行快速审查。范围解析中列出了可接受的审查目标及对应的指令。
若未指定审查目标,按以下顺序确定,找到第一个匹配项后停止:
  1. HEAD
    领先于
    git merge-base origin/<default-branch> HEAD
    :该范围加上所有未提交的变更,需分别说明提交次数和未提交文件数量。
  2. 工作区存在未提交变更:仅审查未提交的变更。
  3. 否则,默认审查
    HEAD~1..HEAD
    范围,并说明这是 fallback 方案。
顺序至关重要:若先检查工作区,一处零散的格式修改可能会掩盖包含12次提交的分支变更,而报告仍会声称覆盖了全部内容。
排除锁文件、快照、生成的输出、第三方依赖代码和二进制文件,并说明排除的内容。若排除后范围为空,需明确说明并停止审查。

2. A Diff Is Not a Surface

2. 差异并非界面本身

A changed file is evidence, not the review subject. Expand each one to the surfaces it renders in and review those.
Expand one hop by default: the direct importers and callers. Expand a second hop only for design tokens, theme values, and shared primitives, where one line reaches the whole product.
Review at most five consumers, ordered by the rule in Scope Resolution, and state how many you did not expand. An unbounded sweep produces coverage claims you cannot support; an unstated cutoff produces a report that looks complete and is not.
变更的文件只是证据,而非审查对象。需将每个变更文件扩展至其渲染的界面,并对这些界面进行审查。
默认扩展一级:直接导入者和调用者。仅针对设计令牌、主题值和共享基础组件扩展二级,因为此类代码的一行变更可能影响整个产品。
最多审查五个消费者,按范围解析中的规则排序,并说明未扩展的数量。无限制的扫描会导致无法支撑的覆盖范围声明;未说明的截断会使报告看似完整实则不然。

3. Read the Removed Lines

3. 读取移除的代码行

Regressions are invisible in the post-change state. Read the
-
side of every hunk against Removed Signals.
A signal is a lead, not a finding. A removal is only a regression when nothing in the change replaces it, and the domain skill owns that judgement. Route each unmatched removal to its owner and report only what that skill confirms. Then status it
Regression
, which tells the author they broke something that worked rather than made a new mistake.
回归问题在变更后的状态中是不可见的。需对照移除信号读取每个代码块的
-
侧内容。
信号只是线索,而非确定的问题。只有当变更未替换被移除的内容时,该移除项才属于回归问题,且该判断由对应领域技能负责。将每个未匹配的移除项移交至其负责技能,仅报告该技能确认的问题。随后标记状态为
Regression
,告知作者他们破坏了原本正常的功能,而非新增了错误。

4. Classify Every Finding

4. 对每个发现进行分类

Give every finding one status:
  • Introduced
    : the change created it.
  • Regression
    : the change weakened something previously correct.
  • Pre-existing
    : present in the touched code but not caused by this change.
Status by what the diff touched, not by which file it sits in: a line the change never touched is
Pre-existing
even three lines from a hunk. Confirm against the base ref when it matters:
bash
git blame -L <line>,<line> "$BASE" -- path/to/file
Hand every finding up with its status attached and let
better-interface
apply its cap and verdict rules.
为每个发现标记一种状态:
  • Introduced
    :变更新增的问题。
  • Regression
    :变更削弱了原本正确的功能。
  • Pre-existing
    :存在于受影响的代码中,但并非由本次变更导致。
根据变更触及的内容标记状态,而非其所在的文件:即使某行代码距离变更块仅三行,但未被变更触及,仍标记为
Pre-existing
。必要时对照基准引用确认:
bash
git blame -L <line>,<line> "$BASE" -- path/to/file
将每个带有状态的发现移交至
better-interface
,由其应用上限和结论规则。

5. Hold the Change to Its Stated Intent

5. 确保变更符合其声明的意图

Read the pull request title and body, the linked issue, and the commit messages, then review whether the interface delivers what they claim.
This is what surfaces the incomplete change, which a surface review cannot see because it inspects states when present and here the point is that they are absent:
  • A new variant, size, or theme applied to some states but not all: hover, focus, active, disabled, loading, selected.
  • A new user-facing string with no entry in the translation catalogue the project maintains.
  • A new component with no empty, loading, error, disabled, or narrow-width state.
  • A control added to one surface but not to the siblings that already carry its peers.
Do not report scope creep. Whether a change does too much is a process question, not an interface one.
读取拉取请求的标题和正文、关联的问题以及提交信息,然后审查界面是否实现了这些声明的内容。
这能发现不完整的变更,此类问题无法通过界面状态审查发现,因为审查的是已存在的状态,而此处的问题在于某些状态缺失:
  • 新的变体、尺寸或主题仅应用于部分状态:悬停(hover)、聚焦(focus)、激活(active)、禁用(disabled)、加载(loading)、选中(selected)。
  • 新增的用户可见字符串未添加至项目维护的翻译目录中。
  • 新增的组件缺少空状态、加载状态、错误状态、禁用状态或窄宽度状态。
  • 在一个界面中添加了控件,但未在已包含同类控件的同级界面中添加。
请勿报告范围蔓延问题。变更是否过度属于流程问题,而非界面问题。

6. Hand the Review to
better-interface

6. 将审查结果移交至
better-interface

With the scope, the affected surfaces, and both sides of the diff in hand, hand the review to
better-interface
with the scope block and a status on every finding. It routes to the six domain skills, applies severity, consolidates, enforces the cap, and issues the verdict, including the change-scoped rules under its Change-Scoped Reviews section.
If
better-interface
is unavailable, report the resolved scope and the file inventory, name it as the missing skill, and stop. Do not invent a severity scale, a cap, or a verdict.
确定范围、受影响的界面及差异的双方内容后,将包含范围块和每个发现状态的审查结果移交至
better-interface
。它会将审查路由至六个领域技能,应用严重性规则、合并结果、执行上限限制并给出最终结论,包括其变更范围审查部分下的变更范围相关规则。
better-interface
不可用,需报告已确定的范围和文件清单,说明该技能缺失,然后停止审查。请勿自行制定严重性等级、上限或结论。

7. Never Mutate the Working Tree

7. 切勿修改工作区

A change review is read-only, including the checkout. Fetch pull request refs; never check them out.
git fetch
writes only to
.git
and is permitted.
gh pr checkout
,
git checkout
,
git switch
, and
git stash
rewrite the files the author has open, failing against local edits or discarding them, and are never permitted in any mode.
Rendered verification is opt-in: mark visual and runtime claims Not verified unless the project exposes a cheap preview or the user asks for a rendered review. When they do, use an isolated worktree (
git worktree add /tmp/review-<n> refs/remotes/pr/<n>
) and remove it when done. That leaves the author's tree untouched, which a checkout does not, so a checkout is not an alternative here.
变更审查是只读操作,包括切换分支。可拉取拉取请求的引用;但切勿检出它们。
git fetch
仅写入
.git
目录,是允许的操作。
gh pr checkout
git checkout
git switch
git stash
会修改作者打开的文件,可能导致本地编辑失败或被丢弃,因此在任何模式下均不允许使用。
渲染验证为可选操作:除非项目提供低成本预览或用户要求进行渲染审查,否则标记视觉和运行时声明为未验证。当用户要求时,使用独立工作区(
git worktree add /tmp/review-<n> refs/remotes/pr/<n>
),审查完成后删除该工作区。这样不会影响作者的工作区,而检出分支则会影响,因此检出分支并非替代方案。

Common Mistakes

常见错误

MistakeFix
One stray edit reviewed instead of the branchCheck
merge-base
before the working tree, and report both counts
Hunks reviewed without their consumersExpand one hop, two for tokens and primitives, and name what you skipped
Only the
+
side of the diff read
Search the
-
side for removed accessibility, focus, motion, and text signals
An equivalent replacement reported as a regressionRoute the removal to the owning skill and report only what it confirms
A removal reported as a new mistakeStatus it
Regression
so the author knows it used to work
A line near a hunk statused
Introduced
Status by what the diff touched, confirmed with
git blame
against the base ref
A pull request checked out to review itFetch the ref and review it in place
Line numbers cited that do not exist on the reviewed refCite against the head ref named in the scope block
Mode, severity, caps, the output format, or the verdict restated hereDefer to
better-interface
Correctness, test, or security findings in the reportName the concern once, point at the project's code review, and drop it
错误修复方案
仅审查了一处零散修改而非整个分支先检查
merge-base
再检查工作区,并报告两种计数
仅审查了代码块而未审查其消费者扩展一级,针对令牌和基础组件扩展二级,并说明跳过的内容
仅读取了差异的
+
侧内容
-
侧查找移除的可访问性、聚焦、动画和文本信号
将等效替换报告为回归问题将移除项移交至负责技能,仅报告其确认的问题
将移除项报告为新增错误标记状态为
Regression
,让作者知道该功能原本正常
将变更块附近的行标记为
Introduced
根据变更触及的内容标记状态,必要时对照基准引用使用
git blame
确认
为审查拉取请求而检出它拉取引用并在原地审查
引用的行号在审查的引用中不存在对照范围块中指定的头部引用进行引用
在此处重述模式、严重性、上限、输出格式或结论交由
better-interface
处理
报告中包含正确性、测试或安全性问题提及一次相关问题,指向项目的通用代码审查,然后不再深入

Review Output Format

审查输出格式

better-interface
owns the format, including the four change-scoped additions under its Change-Scoped Reviews section. Follow it as written and add nothing here.
This skill supplies the scope block:
FieldValue
Target
branch
,
working
,
staged
,
pr 482
, or the range as entered
Base ref
origin/main
at
a1b2c3d
Head ref
refs/remotes/pr/482
at
e4f5g6h
Commits7 committed, 2 files uncommitted
Files in scope12 after exclusions
Excluded
pnpm-lock.yaml
,
src/__snapshots__/
: lockfile and snapshots
Surfaces expanded
CheckoutPage
,
SettingsPanel
; 3 further
Button
consumers not expanded
Plus a status on every finding, per principle 4.
Under
better-interface
's Verification, list the exact
git
and
gh
commands and their results, including every write to
.git
(a fetch, a deepen, a
set-head
, a worktree), so the read-only claim in principle 7 is auditable.
better-interface
负责输出格式,包括其变更范围审查部分下的四个变更范围相关新增内容。需严格遵循该格式,请勿在此处添加任何内容。
本技能提供范围块:
字段
目标
branch
working
staged
pr 482
或输入的范围
基准引用
origin/main
at
a1b2c3d
头部引用
refs/remotes/pr/482
at
e4f5g6h
提交7次已提交,2个未提交文件
范围内文件排除后共12个
排除项
pnpm-lock.yaml
src/__snapshots__/
:锁文件和快照
扩展的界面
CheckoutPage
SettingsPanel
;3个
Button
消费者未扩展
加上每个发现的状态,遵循原则4。
better-interface
验证部分,列出确切的
git
gh
命令及其结果,包括所有对
.git
的写入操作(拉取、加深、设置头部、工作区),以便验证原则7中的只读声明。