interface-review
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseReview 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 skills. Mode, severity, consolidation, coverage, the cap, the output format, and the verdict belong to , which this skill hands the review to. Never duplicate or override their rules here.
better-*better-interfaceCorrectness, 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
快速参考
| Category | When to Use |
|---|---|
| Scope Resolution | Targets and commands, default branch, merge-base, PR and fork refs, repository states, renames, exclusions, consumer expansion |
| Removed Signals | What to look for on the |
| 分类 | 使用场景 |
|---|---|
| 范围解析 | 审查目标与指令、默认分支、合并基准(merge-base)、拉取请求(PR)与分支引用、仓库状态、文件重命名、排除项、消费者扩展 |
| 移除信号 | 需在代码块的 |
Core Principles
核心原则
1. Resolve the Change Scope First
1. 先确定变更范围
better-interface/interface-review quick pr 482quickWith no target supplied, resolve in this order and stop at the first match:
- is ahead of
HEAD: that range plus any uncommitted changes, with the commit count and uncommitted file count stated separately.git merge-base origin/<default-branch> HEAD - The working tree is dirty: the uncommitted changes.
- Otherwise, , stated as a fallback.
HEAD~1..HEAD
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若未指定审查目标,按以下顺序确定,找到第一个匹配项后停止:
- 领先于
HEAD:该范围加上所有未提交的变更,需分别说明提交次数和未提交文件数量。git merge-base origin/<default-branch> HEAD - 工作区存在未提交变更:仅审查未提交的变更。
- 否则,默认审查范围,并说明这是 fallback 方案。
HEAD~1..HEAD
顺序至关重要:若先检查工作区,一处零散的格式修改可能会掩盖包含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 , which tells the author they broke something that worked rather than made a new mistake.
Regression回归问题在变更后的状态中是不可见的。需对照移除信号读取每个代码块的侧内容。
-信号只是线索,而非确定的问题。只有当变更未替换被移除的内容时,该移除项才属于回归问题,且该判断由对应领域技能负责。将每个未匹配的移除项移交至其负责技能,仅报告该技能确认的问题。随后标记状态为,告知作者他们破坏了原本正常的功能,而非新增了错误。
Regression4. Classify Every Finding
4. 对每个发现进行分类
Give every finding one status:
- : the change created it.
Introduced - : the change weakened something previously correct.
Regression - : present in the touched code but not caused by this change.
Pre-existing
Status by what the diff touched, not by which file it sits in: a line the change never touched is even three lines from a hunk. Confirm against the base ref when it matters:
Pre-existingbash
git blame -L <line>,<line> "$BASE" -- path/to/fileHand every finding up with its status attached and let apply its cap and verdict rules.
better-interface为每个发现标记一种状态:
- :变更新增的问题。
Introduced - :变更削弱了原本正确的功能。
Regression - :存在于受影响的代码中,但并非由本次变更导致。
Pre-existing
根据变更触及的内容标记状态,而非其所在的文件:即使某行代码距离变更块仅三行,但未被变更触及,仍标记为。必要时对照基准引用确认:
Pre-existingbash
git blame -L <line>,<line> "$BASE" -- path/to/file将每个带有状态的发现移交至,由其应用上限和结论规则。
better-interface5. 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
better-interface6. 将审查结果移交至better-interface
better-interfaceWith the scope, the affected surfaces, and both sides of the diff in hand, hand the review to 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.
better-interfaceIf 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若不可用,需报告已确定的范围和文件清单,说明该技能缺失,然后停止审查。请勿自行制定严重性等级、上限或结论。
better-interface7. Never Mutate the Working Tree
7. 切勿修改工作区
A change review is read-only, including the checkout. Fetch pull request refs; never check them out. writes only to and is permitted. , , , and rewrite the files the author has open, failing against local edits or discarding them, and are never permitted in any mode.
git fetch.gitgh pr checkoutgit checkoutgit switchgit stashRendered 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 () 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 worktree add /tmp/review-<n> refs/remotes/pr/<n>变更审查是只读操作,包括切换分支。可拉取拉取请求的引用;但切勿检出它们。仅写入目录,是允许的操作。、、和会修改作者打开的文件,可能导致本地编辑失败或被丢弃,因此在任何模式下均不允许使用。
git fetch.gitgh pr checkoutgit checkoutgit switchgit stash渲染验证为可选操作:除非项目提供低成本预览或用户要求进行渲染审查,否则标记视觉和运行时声明为未验证。当用户要求时,使用独立工作区(),审查完成后删除该工作区。这样不会影响作者的工作区,而检出分支则会影响,因此检出分支并非替代方案。
git worktree add /tmp/review-<n> refs/remotes/pr/<n>Common Mistakes
常见错误
| Mistake | Fix |
|---|---|
| One stray edit reviewed instead of the branch | Check |
| Hunks reviewed without their consumers | Expand one hop, two for tokens and primitives, and name what you skipped |
Only the | Search the |
| An equivalent replacement reported as a regression | Route the removal to the owning skill and report only what it confirms |
| A removal reported as a new mistake | Status it |
A line near a hunk statused | Status by what the diff touched, confirmed with |
| A pull request checked out to review it | Fetch the ref and review it in place |
| Line numbers cited that do not exist on the reviewed ref | Cite against the head ref named in the scope block |
| Mode, severity, caps, the output format, or the verdict restated here | Defer to |
| Correctness, test, or security findings in the report | Name the concern once, point at the project's code review, and drop it |
| 错误 | 修复方案 |
|---|---|
| 仅审查了一处零散修改而非整个分支 | 先检查 |
| 仅审查了代码块而未审查其消费者 | 扩展一级,针对令牌和基础组件扩展二级,并说明跳过的内容 |
仅读取了差异的 | 在 |
| 将等效替换报告为回归问题 | 将移除项移交至负责技能,仅报告其确认的问题 |
| 将移除项报告为新增错误 | 标记状态为 |
将变更块附近的行标记为 | 根据变更触及的内容标记状态,必要时对照基准引用使用 |
| 为审查拉取请求而检出它 | 拉取引用并在原地审查 |
| 引用的行号在审查的引用中不存在 | 对照范围块中指定的头部引用进行引用 |
| 在此处重述模式、严重性、上限、输出格式或结论 | 交由 |
| 报告中包含正确性、测试或安全性问题 | 提及一次相关问题,指向项目的通用代码审查,然后不再深入 |
Review Output Format
审查输出格式
better-interfaceThis skill supplies the scope block:
| Field | Value |
|---|---|
| Target | |
| Base ref | |
| Head ref | |
| Commits | 7 committed, 2 files uncommitted |
| Files in scope | 12 after exclusions |
| Excluded | |
| Surfaces expanded | |
Plus a status on every finding, per principle 4.
Under 's Verification, list the exact and commands and their results, including every write to (a fetch, a deepen, a , a worktree), so the read-only claim in principle 7 is auditable.
better-interfacegitgh.gitset-headbetter-interface本技能提供范围块:
| 字段 | 值 |
|---|---|
| 目标 | |
| 基准引用 | |
| 头部引用 | |
| 提交 | 7次已提交,2个未提交文件 |
| 范围内文件 | 排除后共12个 |
| 排除项 | |
| 扩展的界面 | |
加上每个发现的状态,遵循原则4。
在的验证部分,列出确切的和命令及其结果,包括所有对的写入操作(拉取、加深、设置头部、工作区),以便验证原则7中的只读声明。
better-interfacegitgh.git