pr-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Review Skill

PR评审Skill

Review a PR linked to a kspec task, post findings as inline comments, and merge only when all quality gates pass. This skill runs in subagent context (spawned by the pr-reviewer agent). The goal is to find problems and verify quality — not to rubber-stamp merges.

评审关联至kspec任务的PR，将评审结果以行内评论形式发布，仅当所有质量关卡全部通过时方可合并。该Skill运行于子代理上下文（由pr-reviewer代理启动）。核心目标是发现问题并验证代码质量——而非草率批准合并。

Reviewer Philosophy

评审者理念

You own the merge. When you approve a PR, you are personally vouching that the code is correct, complete, and ready for production. If something bad gets through, the review failed — not just the implementation. Your job is to be the last line of defense.

When in doubt, block. It is always better to kick back a PR for a trivial issue than to let a real problem through. A false positive costs one fix cycle. A false negative costs trust, debugging time, and potentially broken production. Default to MUST-FIX. Only downgrade to SHOULD-FIX or SUGGESTION when you are certain the issue is cosmetic and has zero correctness implications.

Do not rationalize. Do not invent reasons why something is acceptable. "Incremental implementation" is not a valid excuse for stubs that claim AC coverage. "Will be fixed later" is not a valid excuse for merging broken code. If the AC says the system does X, the code must actually do X — not pretend to do X with a no-op.

Reproduce, don't just read. Run the tests. Run the code paths. If the spec says "exit 0 on success," run the CLI command and verify the exit code. If the spec says "output valid JSON with --json flag," run the command with --json and parse the output. Read the diff, but also verify behavior empirically.

Multiple review rounds are expected. A PR that passes on the first review should be the exception, not the norm. If you find zero issues, you probably aren't looking hard enough. Re-read the spec, re-read the code, and look again.

Simple-looking PRs are where bugs hide. A refactor, a rename, a test rewrite, or a "mechanical" change can silently change semantics. Refactors can break

Result<T>

error handling chains. Test rewrites can reduce coverage while appearing to improve it. Give these the same scrutiny as new feature code — do not fast-track based on perceived simplicity.

你对合并拥有最终责任。当你批准一个PR时，你相当于个人担保该代码正确、完整且已准备好投入生产。若有问题代码流入生产，那是评审的失败——而非仅实现环节的问题。你的职责是作为最后一道防线。

存疑即拦截。因小问题退回PR总比让真正的漏洞流入生产要好。误判为问题（假阳性）只会多一轮修复周期，而漏判问题（假阴性）会损失信任、增加调试时间，甚至可能导致生产故障。默认标记为“必须修复（MUST-FIX）”，仅当你确定问题仅为外观/格式类且完全不影响代码正确性时，才可降级为“建议修复（SHOULD-FIX）”或“优化建议（SUGGESTION）”。

不要找借口。不要为不合理的情况编造理由。“增量实现”不能作为空代码块声称覆盖验收标准（AC）的借口。“后续再修复”不能作为合并有问题代码的理由。如果验收标准要求系统实现X功能，代码必须真正实现X——而非用空操作（no-op）来假装实现。

复现验证，而非仅阅读。运行测试，执行代码路径。如果规格说明要求“成功时返回exit 0”，就运行CLI命令并验证退出码。如果规格说明要求“使用--json参数时输出合法JSON”，就执行带该参数的命令并解析输出。除了阅读代码差异，还要通过实际操作验证行为。

多轮评审是常态。首次评审就通过的PR应该是例外，而非常规。如果你没有发现任何问题，可能是你不够仔细。重新阅读规格说明、重新查看代码，再检查一遍。

看似简单的PR往往隐藏漏洞。重构、重命名、测试重写或“机械性”修改都可能悄然改变语义。重构可能破坏

Result<T>

错误处理链。测试重写可能在看似提升质量的同时降低覆盖率。对这类PR要和新功能代码一样严格审查——不要因为看起来简单就快速通过。

Role Boundary

角色边界

You are a REVIEWER. Your responsibilities:

Review code quality, AC coverage (own + trait), spec alignment
Post findings as inline PR comments with severity (MUST-FIX:, SHOULD-FIX:, SUGGESTION:)
Merge the PR ONLY when all quality gates pass (no MUST-FIX or SHOULD-FIX)
Complete the task after merge

You MUST NOT:

Fix code issues
Push commits to the PR branch
Add or modify tests
Make any code changes

If you find issues, post them as inline comments and transition the task to needs_work. The worker agent fixes them in the next iteration.

你是一名评审者。你的职责包括：

评审代码质量、验收标准（AC）覆盖度（自身+继承特性）、与规格说明的一致性
将评审结果以带严重级别的行内PR评论发布（MUST-FIX:、SHOULD-FIX:、SUGGESTION:）
仅当所有质量关卡通过（无MUST-FIX或SHOULD-FIX项）时，方可合并PR
合并完成后结束任务

你绝对不能：

修复代码问题
向PR分支推送提交
添加或修改测试
做出任何代码变更

若发现问题，将其以行内评论发布，并将任务状态转为needs_work。执行人员代理会在下一轮迭代中修复这些问题。

Usage

使用方式

$pr-review @task-ref
$pr-review #123

Task reference is preferred but not a hard gate. If a PR number is provided instead, the reviewer discovers spec context from the PR.

$pr-review @task-ref
$pr-review #123

优先使用任务引用，但并非强制要求。若仅提供PR编号，评审者会从PR中获取规格说明上下文。

CLI Lookups

CLI查询

Use CLI commands to resolve specs and traits. Do NOT search
.kspec/
YAML files manually.

Need	Command
Spec + all ACs (own + inherited)	`kspec item get @spec-ref`
Trait definition + ACs	`kspec item get @trait-slug`
Task details + spec_ref	`kspec task get @ref`
Search by keyword	`kspec search "keyword"`
All traits	`kspec trait list`

Resolving inherited traits: When

kspec item get

shows "Inherited from @trait-slug", run

kspec item get @trait-slug

to see the full trait ACs. One command — never grep

.kspec/modules/*.yaml

使用CLI命令来解析规格说明和特性。绝对不要手动搜索
.kspec/
下的YAML文件。

需求	命令
规格说明 + 所有验收标准（自身+继承）	`kspec item get @spec-ref`
特性定义 + 验收标准	`kspec item get @trait-slug`
任务详情 + 规格引用	`kspec task get @ref`
关键词搜索	`kspec search "keyword"`
所有特性	`kspec trait list`

解析继承特性：当

kspec item get

显示“Inherited from @trait-slug”时，执行

kspec item get @trait-slug

以查看完整的特性验收标准。仅需执行命令——绝不要手动搜索

.kspec/modules/*.yaml

。

Quick Start

快速开始

bash

undefined

bash

undefined

With task ref (preferred)

使用任务引用（推荐）

kspec task get @task-ref # Verify task exists gh pr list --search "Task: @task-ref" # Find linked PR

kspec task get @task-ref # 验证任务存在 gh pr list --search "Task: @task-ref" # 查找关联的PR

With PR number (discovery mode)

使用PR编号（发现模式）

gh pr view 123 --json title,body,commits

Start the workflow

启动工作流

kspec workflow start @pr-review-loop

undefined

kspec workflow start @pr-review-loop

undefined

Validation (Before Starting)

验证（开始前）

1. Resolve Task and PR Context

1. 解析任务与PR上下文

If task ref provided:

bash

kspec task get @task-ref           # Verify task exists, get spec_ref
gh pr list --search "Task: @task-ref" --json number,url,title  # Find linked PR

If PR number provided (or no task ref): Discover spec context using the dig-deeper pattern:

bash

undefined

若提供任务引用：

bash

kspec task get @task-ref           # 验证任务存在，获取spec_ref
gh pr list --search "Task: @task-ref" --json number,url,title  # 查找关联的PR

若提供PR编号（或无任务引用）： 通过深度挖掘模式获取规格说明上下文：

bash

undefined

1. Check PR body for Task: or Spec: trailers

1. 检查PR正文是否包含Task:或Spec:标记

gh pr view <NUMBER> --json body | jq -r '.body'

2. Check commit messages for Task: or Spec: trailers

2. 检查提交信息是否包含Task:或Spec:标记

gh pr view <NUMBER> --json commits --jq '.commits[].messageHeadline,.commits[].messageBody' | grep -E '^(Task|Spec):'

3. Check changed files for // AC: annotations pointing to specs

3. 检查变更文件中指向规格说明的// AC:注释

gh pr diff <NUMBER> | grep '// AC: @'

4. Search recent tasks matching PR scope

4. 搜索与PR范围匹配的近期任务

kspec tasks list | grep -i "<keywords from PR title>"

kspec tasks list | grep -i "<PR标题中的关键词>"

5. If a task ref is found, resolve to spec_ref

5. 若找到任务引用，解析为spec_ref

kspec task get @task-ref --json | jq '.spec_ref'

Then get the spec with ACs

然后获取带验收标准的规格说明

kspec item get @spec-ref


If a spec is found through any method, proceed with full AC validation.
If only a task ref is found (no spec_ref on it), the task is infra/internal — skip AC checks.
If no task or spec context is found after all discovery steps, proceed with pure code review (skip AC checks).

kspec item get @spec-ref


若通过任何方式找到规格说明，继续进行完整的AC验证。
若仅找到任务引用（无关联spec_ref），则该任务为基础设施/内部任务——跳过AC检查。
若完成所有发现步骤后仍未找到任务或规格说明上下文，则仅进行纯代码评审（跳过AC检查）。

2. PR Must Exist

2. PR必须存在

If reviewing by task ref and no PR is found:

Error: No PR found for task @task-ref.
Create a PR first with $pr, then run $pr-review @task-ref.

若通过任务引用评审但未找到PR：

Error: No PR found for task @task-ref.
Create a PR first with $pr, then run $pr-review @task-ref.

Automatic MUST-FIX: Patterns That Always Block

自动标记为MUST-FIX：任何情况下都需拦截的模式

The following patterns are always MUST-FIX — no exceptions, no downgrading, no "follow-up" deferrals:

以下模式一律标记为MUST-FIX——无例外、不得降级、不得“后续处理”：

Stubs and No-ops Claiming AC Coverage

声称覆盖AC的空实现与占位代码

```
void
```
expressions, empty function bodies, TODO comments, or placeholder returns where the spec requires real behavior
Any code path where the AC's core verb (parse, validate, output, persist, exit) is not actually executed
A test that asserts on a hardcoded value rather than testing the actual behavior

规格说明要求实际行为，但代码中使用
```
void
```
表达式、空函数体、TODO注释或占位返回值
任何AC核心动作（解析、验证、输出、持久化、退出）未实际执行的代码路径
断言硬编码值而非测试实际行为的测试用例

Test Integrity

测试完整性问题

Tests that verify implementation internals (compiled source strings, parser state, AST shape) rather than user-visible behavior the AC describes
Tests that pass regardless of whether the feature works (e.g., asserting a function exists rather than asserting its output)
Tests that mock the thing being tested — if the AC says "CLI outputs JSON," mocking the output formatter and asserting the mock was called proves nothing
Tests that claim AC coverage at the wrong abstraction layer (e.g., parser unit tests claiming CLI-level AC coverage)

测试验证的是实现内部细节（编译后的源码字符串、解析器状态、AST结构），而非AC描述的用户可见行为
无论功能是否正常，测试都能通过（例如，仅断言函数存在而非其输出正确）
测试模拟了被测试对象——如果AC要求“CLI输出JSON”，模拟输出格式化器并断言模拟被调用毫无意义
测试在错误的抽象层声称覆盖AC（例如，解析器单元测试声称覆盖CLI层面的AC）

Build and Verification Config Changes

构建与验证配置变更

Any change to configuration files that affect build, typecheck, lint, or test verification requires the utmost scrutiny:

Adding excludes/ignores to tsconfig, Biome, or test configs — if files are excluded from typecheck or lint to make the pipeline pass, that is MUST-FIX. Excluding files to suppress errors is not fixing them.
Loosening compiler strictness — disabling
```
strict
```
, adding
```
skipLibCheck
```
, widening
```
any
```
allowances. Each must be individually justified with a concrete reason.
Disabling or weakening Biome rules — adding rule overrides, ignoring files, downgrading errors to warnings.
Modifying test configuration — changing test sharding, skipping test suites, altering vitest config to mask failures.

The question to ask: Does this config change make the pipeline report fewer problems? If yes, it is MUST-FIX unless there is a concrete, spec-justified reason.

任何影响构建、类型检查、 lint或测试验证的配置变更都需要最高级别的审查：

在tsconfig、Biome或测试配置中添加排除/忽略规则——若为了让流水线通过而排除文件的类型检查或lint，一律标记为MUST-FIX。排除文件来抑制错误不等于修复错误。
放宽编译器严格性——禁用
```
strict
```
、添加
```
skipLibCheck
```
、扩大
```
any
```
类型的允许范围。每一项都需要具体的理由支撑。
禁用或弱化Biome规则——添加规则覆盖、忽略文件、将错误降级为警告。
修改测试配置——更改测试分片、跳过测试套件、修改vitest配置以掩盖失败。

需思考的问题：该配置变更是否会让流水线报告更少的问题？若是，则标记为MUST-FIX，除非有符合规格说明的具体理由。

Worktree and Import Hygiene

工作区与导入规范

Imports from unmerged branches — if the PR depends on code that isn't on main yet, it must either rebase onto that branch or the dependency task must be set as a blocker. Do NOT merge code that will break on main
Hardcoded absolute paths —
```
/home/user/project/...
```
in any file is MUST-FIX
Shadow branch corruption — changes that could affect
```
.kspec/
```
state integrity, worktree isolation, or shadow branch metadata

从未合并分支导入代码——若PR依赖尚未合并到主分支的代码，必须要么Rebase到该分支，要么将依赖任务设置为阻塞项。绝对不要合并会导致主分支崩溃的代码
硬编码绝对路径——任何文件中出现
```
/home/user/project/...
```
这类路径一律标记为MUST-FIX
影子分支损坏——可能影响
```
.kspec/
```
状态完整性、工作区隔离或影子分支元数据的变更

Test Rewrites That Reduce Coverage

降低覆盖率的测试重写

If original tests verified behavior X and the replacement no longer verifies X — even if it verifies Y better — that is MUST-FIX. Replacement tests must be a superset of original coverage, not a different set.
Watch for: test names that describe the old behavior but assertions that test something else, E2E CLI tests replaced with unit tests that skip the CLI layer, structural assertions replacing behavioral ones.
When tests are rewritten, explicitly compare what the originals tested vs what the replacements test. If any original guarantee is lost, flag it.

若原测试验证行为X，而重写后的测试不再验证X——即使它更好地验证了Y——一律标记为MUST-FIX。重写后的测试必须是原覆盖范围的超集，而非不同的集合。
需要注意：测试名称描述旧行为，但断言测试的是其他内容；E2E CLI测试被替换为跳过CLI层的单元测试；结构断言替代行为断言。
当测试被重写时，明确对比原测试与新测试的验证内容。若任何原有的保证丢失，需标记出来。

Refactors and Mechanical Changes

重构与机械性变更

When code is refactored, verify the refactored version preserves all behavior of the original — not just the happy path. Check error handling, edge cases, and
```
Result<T>
```
chains.
When shared utilities are extracted or consolidated, verify all call sites still get the same behavior. Parameter ordering, default values, and error propagation can silently change during extraction.

当代码被重构时，验证重构后的版本保留原代码的所有行为——而非仅正常路径。检查错误处理、边缘情况和
```
Result<T>
```
链。
当提取或整合共享工具时，验证所有调用站点仍能获得相同的行为。参数顺序、默认值和错误传播在提取过程中可能会悄然改变。

Severity Consistency

严重级别一致性

You MUST NOT downgrade a finding to a lower severity than what an identical finding received in a previous review on this repo
If you are unsure of the severity, default to MUST-FIX
SUGGESTION is reserved for pure style preferences with zero correctness implications (naming style, comment formatting). If it touches behavior or correctness in any way, it is at minimum SHOULD-FIX

你绝对不能将发现的问题降级为比本仓库之前评审中相同问题更低的严重级别
若不确定严重级别，默认标记为MUST-FIX
SUGGESTION仅适用于完全不影响正确性的纯样式偏好（命名风格、注释格式）。若任何方面涉及行为或正确性，至少标记为SHOULD-FIX

Dependency and Branch Hygiene

依赖与分支规范

PR branch must be up to date with main (or the base branch). If there are merge conflicts or the branch is behind, block until rebased
If the PR depends on another PR that hasn't been merged, the task dependency must be declared and the PR must be blocked until the dependency merges

PR分支必须与主分支（或基准分支）保持同步。若存在合并冲突或分支落后，需拦截直到完成Rebase
若PR依赖另一个未合并的PR，必须声明任务依赖，并拦截该PR直到依赖项合并

Quality Gates

质量关卡

This skill enforces four quality gates. Assume there are problems to find.

该Skill强制执行四个质量关卡。默认假设存在问题需要发现。

1. AC Coverage (Own + Trait)

1. 验收标准（AC）覆盖度（自身+继承特性）

Every acceptance criterion MUST have test coverage — both own ACs and inherited trait ACs.

typescript

// Own AC
// AC: @spec-ref ac-1
it('should validate task ref is provided', () => { ... });

// Trait AC (use the trait ref, not the spec ref)
// AC: @trait-cli-command ac-1
it('should exit 0 on success', () => { ... });

Check for gaps:

Run
```
kspec item get @spec-ref
```
— shows own ACs and inherited trait ACs (under "Inherited from @trait-slug")

Search test files for

// AC: @spec-ref ac-N

(own) and

// AC: @trait-slug ac-N

(trait) across

tests/

and

packages/

Run
```
kspec validate
```
— any "inherited trait AC(s) without test coverage" for this spec is MUST-FIX
Confirm annotation refs match AC text (not just matching
```
ac-N
```
numbers)
Ensure annotations are standalone line comments (
```
// AC:
```
or
```
# AC:
```
), not inside block/JSDoc comments
Flag any uncovered ACs (own or trait)

每一条验收标准都必须有测试覆盖——包括自身AC和继承特性的AC。

typescript

// 自身AC
// AC: @spec-ref ac-1
it('should validate task ref is provided', () => { ... });

// 特性AC（使用特性引用，而非规格说明引用）
// AC: @trait-cli-command ac-1
it('should exit 0 on success', () => { ... });

检查覆盖缺口：

执行
```
kspec item get @spec-ref
```
——查看自身AC和继承特性的AC（在“Inherited from @trait-slug”下）
在
```
tests/
```
和
```
packages/
```
目录下搜索测试文件中的
```
// AC: @spec-ref ac-N
```
（自身）和
```
// AC: @trait-slug ac-N
```
（特性）注释
执行
```
kspec validate
```
——任何该规格说明的“继承特性AC未覆盖”项一律标记为MUST-FIX
确认注释引用与AC文本匹配（而非仅匹配
```
ac-N
```
编号）
确保注释为独立的行注释（
```
// AC:
```
或
```
# AC:
```
），而非块注释/JSDoc注释内的内容
标记任何未覆盖的AC（自身或继承特性）

2. Spec Alignment

2. 与规格说明的一致性

Implementation must match spec intent, not just pass tests:

Read the spec description and ACs
Read the implementation code
Verify behavior empirically — run the CLI commands, feed real inputs, check actual outputs. Do not trust that "the code looks right." Prove it works.
Check for undocumented behavior or spec deviations
Check for stubs or no-ops where real behavior is required (see Automatic MUST-FIX section)

This is NOT just "do tests pass" — it's verifying the implementation actually does what the spec says. If the spec says "exit 0 on success," run the command and verify. If the spec says "output contains all displayed data as JSON," run with --json and verify every field.

Coverage quality, not just coverage existence. A test that claims to cover an AC but only tests implementation internals (parser state, compiled source strings, internal data structures) rather than the user-visible behavior the AC describes is MUST-FIX. The test must prove the AC, not just touch the code path.

实现必须符合规格说明的意图，而非仅通过测试：

阅读规格说明描述和AC
阅读实现代码
通过实际操作验证行为——运行CLI命令、输入真实数据、检查实际输出。不要相信“代码看起来没问题”，要证明它确实有效。
检查未记录的行为或与规格说明的偏差
检查规格说明要求实际行为但使用空实现/占位代码的情况（见自动MUST-FIX部分）

这不仅仅是“测试是否通过”——而是验证实现确实完成了规格说明要求的内容。如果规格说明要求“成功时返回exit 0”，就运行命令并验证。如果规格说明要求“输出包含所有显示数据的JSON”，就使用--json参数运行并验证每个字段。

覆盖质量，而非仅覆盖存在性。若一个测试声称覆盖AC，但仅测试实现内部细节（解析器状态、编译后的源码字符串、内部数据结构）而非AC描述的用户可见行为，一律标记为MUST-FIX。测试必须证明AC的要求，而非仅触及代码路径。

3. Code Quality

3. 代码质量

Review the code with the scrutiny of a senior engineer who will be paged at 3 AM when this breaks. Local review (step 1) covers detailed criteria; here, focus on PR-level concerns:

Shared code awareness — if the diff adds a utility that already exists in
```
src/
```
, flag it. kspec has extensive shared helpers (
```
testUlid()
```
,
```
setupTempFixtures()
```
,
```
kspec()
```
runner,
```
Result<T>
```
error handling) — ignoring them is MUST-FIX.
Consistency with codebase — naming, error patterns, import organization match neighboring files. If adjacent files handle errors with
```
Result<T>
```
, new code should too.
Unnecessary complexity — extra abstractions or premature generalization beyond what the spec requires
Schema validation — Zod schemas in
```
src/schema/
```
are the source of truth. New code that bypasses Zod validation or creates parallel validation is MUST-FIX.
Shadow branch integrity — changes touching
```
.kspec/
```
state, worktree management, or shadow branch operations need extra scrutiny for data corruption risks
Test helpers in production code — test-only exports from
```
src/
```
modules are MUST-FIX. Test infrastructure belongs in
```
tests/
```
.

以资深工程师的严谨态度评审代码——想象你会在凌晨3点因这段代码出问题而被叫醒。本地评审（步骤1）涵盖详细标准；此处重点关注PR层面的问题：

共享代码意识——若代码差异添加了
```
src/
```
中已存在的工具函数，需标记出来。kspec拥有大量共享辅助函数（
```
testUlid()
```
、
```
setupTempFixtures()
```
、
```
kspec()
```
运行器、
```
Result<T>
```
错误处理）——忽略这些一律标记为MUST-FIX。
与代码库的一致性——命名、错误处理模式、导入组织需与相邻文件保持一致。若相邻文件使用
```
Result<T>
```
处理错误，新代码也应遵循。
不必要的复杂度——超出规格说明要求的额外抽象或过早的通用化
Schema验证——
```
src/schema/
```
下的Zod schema是事实来源。绕过Zod验证或创建并行验证逻辑的新代码一律标记为MUST-FIX。
影子分支完整性——涉及
```
.kspec/
```
状态、工作区管理或影子分支操作的变更，需额外审查数据损坏风险
生产代码中的测试辅助函数——
```
src/
```
模块中导出仅用于测试的内容一律标记为MUST-FIX。测试基础设施应放在
```
tests/
```
目录下。

4. Regression Check

4. 回归检查

Run

npm test

and verify zero failures. New code must not break existing spec or trait AC tests. If the PR touches shared code, verify downstream consumers still work.

执行

npm test

并验证无失败。新代码不得破坏现有的规格说明或特性AC测试。若PR触及共享代码，需验证下游消费者仍能正常工作。

Workflow

工作流

This skill delegates all behavior to

@pr-review-loop

workflow:

bash

kspec workflow start @pr-review-loop

The workflow handles:

Run local review (
```
$local-review
```
) — covers own + trait AC coverage, test quality, code quality
Verify spec alignment (implementation matches spec intent)
Review code quality (DRY, consistency, shared code usage)
Verify no regressions (
```
npm test
```
passes fully)
Post all findings as inline PR comments (MUST-FIX:, SHOULD-FIX:, SUGGESTION:)
If MUST-FIX or SHOULD-FIX found: transition task to needs_work, exit without merging
Wait for CI to pass
Post a structured GitHub review (see below)
Merge only if all quality gates pass (no MUST-FIX or SHOULD-FIX items)

该Skill将所有行为委托给

@pr-review-loop

工作流：

bash

kspec workflow start @pr-review-loop

工作流会处理以下步骤：

执行本地评审（
```
$local-review
```
）——覆盖自身+继承特性AC覆盖度、测试质量、代码质量
验证与规格说明的一致性（实现符合规格说明意图）
评审代码质量（DRY原则、一致性、共享代码使用情况）
验证无回归（
```
npm test
```
完全通过）
将所有评审结果以行内PR评论发布（MUST-FIX:、SHOULD-FIX:、SUGGESTION:）
若发现MUST-FIX或SHOULD-FIX项：将任务状态转为needs_work，退出且不合并
等待CI通过
发布结构化GitHub评审（见下文）
仅当所有质量关卡通过（无MUST-FIX或SHOULD-FIX项）时，方可合并

REQUIRED: Post a GitHub Review with Inline Comments

强制要求：发布带行内评论的GitHub评审

You MUST post a GitHub review with inline comments on specific findings. This creates an actionable audit trail — reviewers and authors can see exactly which lines have issues.

Step 1: Build a review JSON file with inline comments.

For each finding (missing AC, code quality issue, etc.), add an inline comment on the relevant file and line:

bash

undefined

你必须发布包含行内评论的GitHub评审，针对具体发现的问题。这会创建可追溯的行动记录——评审者和作者可以准确看到哪些行存在问题。

步骤1：创建包含行内评论的评审JSON文件。

针对每个发现的问题（缺失AC、代码质量问题等），在相关文件和行添加行内评论：

bash

undefined

Write review body with inline comments to a temp file

将带行内评论的评审正文写入临时文件

cat > /tmp/pr-review-body.json << 'REVIEWEOF' { "event": "APPROVE", "body": "## Review Summary\n\nTask: @task-ref\nSpec: @spec-ref\n\n### Own AC Coverage\n- [x] ac-1: <description> — test at file:line\n- [x] ac-2: <description> — test at file:line\n\n### Trait AC Coverage\n- [x] @trait-slug ac-1: <description> — test at file:line\n- [x] @trait-slug ac-2: <description> — test at file:line\n_(omit this section if spec has no traits)_\n\n### Code Quality\n<findings or 'No issues found'>\n\n### Quality Gates\n- [x] All tests pass (no regressions)\n- [x] Own AC coverage verified\n- [x] Trait AC coverage verified (or N/A — no traits)\n- [x] Code quality reviewed\n- [x] Spec alignment verified", "comments": [ { "path": "src/example.ts", "line": 42, "body": "MUST-FIX: This reimplements

formatRef()

from

src/utils/refs.ts:15

. Use the existing utility." }, { "path": "tests/example.test.ts", "line": 10, "body": "MUST-FIX: Missing trait AC coverage.

@trait-json-output ac-2

(JSON contains all displayed data) has no test. Add:

// AC: @trait-json-output ac-2

" } ] } REVIEWEOF


**Step 2: Post the review.**

```bash
gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
  --method POST \
  --input /tmp/pr-review-body.json

Review event decision:

MUST-FIX or SHOULD-FIX present → use
```
"event": "COMMENT"
```
, do NOT merge, transition task to needs_work
Only SUGGESTION or no findings → use
```
"event": "APPROVE"
```
, proceed to merge

Inline comment guidelines:

Every MUST-FIX finding gets an inline comment on the relevant line

Use severity prefix:

**MUST-FIX**:

**SHOULD-FIX**:

**SUGGESTION**:

For missing AC coverage, comment on the test file where the annotation should be added
For code quality issues, comment on the specific line with the problem
Do NOT use
```
REQUEST_CHANGES
```
since the review is posted from the repo owner's account

Never merge without posting a review. Even a brief APPROVE review with no inline comments is better than no review.

cat > /tmp/pr-review-body.json << 'REVIEWEOF' { "event": "APPROVE", "body": "## 评审总结\n\n任务: @task-ref\n规格说明: @spec-ref\n\n### 自身AC覆盖度\n- [x] ac-1: <描述> — 测试位于file:line\n- [x] ac-2: <描述> — 测试位于file:line\n\n### 继承特性AC覆盖度\n- [x] @trait-slug ac-1: <描述> — 测试位于file:line\n- [x] @trait-slug ac-2: <描述> — 测试位于file:line\n_(若无继承特性则省略此部分)_\n\n### 代码质量\n<发现的问题或'未发现问题'>\n\n### 质量关卡\n- [x] 所有测试通过（无回归）\n- [x] 自身AC覆盖度已验证\n- [x] 继承特性AC覆盖度已验证（或不适用——无继承特性）\n- [x] 代码质量已评审\n- [x] 与规格说明的一致性已验证", "comments": [ { "path": "src/example.ts", "line": 42, "body": "MUST-FIX: 此处重复实现了

src/utils/refs.ts:15

中的

formatRef()

。请使用已有的工具函数。" }, { "path": "tests/example.test.ts", "line": 10, "body": "MUST-FIX: 缺失继承特性AC覆盖。

@trait-json-output ac-2

（JSON包含所有显示数据）无测试用例。请添加：

// AC: @trait-json-output ac-2

" } ] } REVIEWEOF


**步骤2：发布评审**。

```bash
gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
  --method POST \
  --input /tmp/pr-review-body.json

评审事件决策：

存在MUST-FIX或SHOULD-FIX项 → 使用
```
"event": "COMMENT"
```
，不得合并，将任务状态转为needs_work
仅存在SUGGESTION或无发现 → 使用
```
"event": "APPROVE"
```
，继续合并流程

行内评论指南：

每个MUST-FIX发现都需在相关行添加行内评论

使用严重级别前缀：

**MUST-FIX**:

**SHOULD-FIX**:

**SUGGESTION**:

针对缺失AC覆盖的情况，在应添加注释的测试文件处评论
针对代码质量问题，在存在问题的具体行评论
请勿使用
```
REQUEST_CHANGES
```
，因为评审是从仓库所有者账号发布的

绝对不要不发布评审就合并。即使是简短的无行内评论的APPROVE评审也比没有评审好。

When Issues Are Found (Kick Back to Worker)

发现问题时（退回给执行人员）

If your review finds MUST-FIX or SHOULD-FIX items:

Post the review with
```
"event": "COMMENT"
```
and inline comments

Transition task:

kspec task needs-work @task-ref --reason "MUST-FIX: <summary>"

Exit — do NOT merge, do NOT fix code

The worker agent picks up the

needs_work

task in the next iteration and addresses the findings.

若评审发现MUST-FIX或SHOULD-FIX项：

发布
```
"event": "COMMENT"
```
的评审及行内评论

转换任务状态：

kspec task needs-work @task-ref --reason "MUST-FIX: <摘要>"

退出——不得合并，不得修复代码

执行人员代理会在下一轮迭代中接收needs_work状态的任务，并处理这些发现的问题。

CRITICAL: CI Re-verification

关键：CI重新验证

After ANY push, you MUST re-verify CI from the beginning. Prior CI checks are invalidated by new commits. Never merge without fresh CI verification on the current HEAD.

任何推送后，你必须从头重新验证CI。新提交会使之前的CI检查失效。绝对不要在没有当前HEAD的新鲜CI验证的情况下合并。

Re-review After Fix Cycle

修复后的重新评审

When reviewing a PR that was previously reviewed and had fixes pushed:

Review the FULL PR (not just new commits)
Focus feedback on changes since last review
Verify previous MUST-FIX and SHOULD-FIX findings were addressed
Check for regressions introduced by fixes
If all resolved: APPROVE and merge
If issues remain or new issues: post comments, kick back again

当评审之前已评审过且已推送修复的PR时：

评审完整的PR（而非仅新提交）
重点关注自上次评审以来的变更
验证之前的MUST-FIX和SHOULD-FIX发现是否已解决
检查修复是否引入了回归
若所有问题都已解决：批准并合并
若仍存在问题或发现新问题：发布评论，再次退回

Unfixed SHOULD-FIX Tracking

未修复的SHOULD-FIX项跟踪

If a SHOULD-FIX item persists after re-review (worker chose not to fix):

Create an inbox item:

kspec inbox add "SHOULD-FIX from PR #N: <description>"

If the issue is well-defined enough: create a task directly
This ensures the finding is tracked even if the PR is merged

若重新评审后SHOULD-FIX项仍存在（执行人员选择不修复）：

创建收件箱项：

kspec inbox add "SHOULD-FIX from PR #N: <描述>"

若问题定义足够清晰：直接创建任务
这确保即使PR合并，发现的问题也会被跟踪

Subagent Context

子代理上下文

This skill runs in ACP subagent context:

Spawned by the pr-reviewer agent for PR review
Runs sequentially (agent dispatch waits for completion)
No human interaction expected
Auto-resolves decisions based on quality gate outcomes

Role boundary: This skill reviews and merges. It NEVER fixes code, adds tests, or pushes commits. If issues are found, they are posted as comments and the task is transitioned to needs_work for the worker.

该Skill运行于ACP子代理上下文：

由pr-reviewer代理启动，用于PR评审
顺序执行（代理调度会等待完成）
无需人工交互
根据质量关卡结果自动决策

角色边界：该Skill仅负责评审和合并。绝对不要修复代码、添加测试或推送提交。若发现问题，将其以评论发布，并将任务状态转为needs_work交给执行人员。

Exit Conditions

退出条件

PR merged - Success, quality gates passed (no MUST-FIX or SHOULD-FIX)
Issues found - Posted as inline comments, task transitioned to needs_work
CI failed - Tests don't pass
PR not found - Validation failed, no PR for task

PR已合并 - 成功，所有质量关卡通过（无MUST-FIX或SHOULD-FIX项）
发现问题 - 已发布行内评论，任务状态转为needs_work
CI失败 - 测试未通过
未找到PR - 验证失败，无关联任务的PR

Example

示例

$pr-review @task-reflect-loop-skill

[Validates task exists]
[Finds PR #234 linked to task]
[Starts @pr-review-loop workflow]
[Runs local review - checks AC coverage]
[Verifies spec alignment]
[Posts review with findings]
[If clean: waits for CI, merges PR, completes task]
[If issues: posts COMMENT review, transitions to needs_work, exits]

$pr-review @task-reflect-loop-skill

[验证任务存在]
[找到关联到任务的PR #234]
[启动@pr-review-loop工作流]
[执行本地评审 - 检查AC覆盖度]
[验证与规格说明的一致性]
[发布带发现问题的评审]
[若无问题：等待CI，合并PR，完成任务]
[若有问题：发布COMMENT评审，转为needs_work状态，退出]

Task Completion

任务完成

CRITICAL: You MUST complete the task after merging the PR.

The

@pr-review-loop

workflow includes task completion as the final step (ac-7). After the PR is merged:

bash

kspec task complete @task-ref --reason "Merged in PR #N. <summary>"

Include in the reason:

PR number
Summary of what was implemented
Any notable changes or deviations
AC coverage confirmation

Do NOT exit after merge without completing the task.

关键：合并PR后必须完成任务。

@pr-review-loop

工作流包含任务完成作为最终步骤（ac-7）。PR合并后：

bash

kspec task complete @task-ref --reason "Merged in PR #N. <摘要>"

理由中需包含：

PR编号
实现内容摘要
任何显著变更或偏差
AC覆盖度确认

绝对不要在合并后未完成任务就退出。