AGENT SKILL

review

暂无简介

License 许可
MIT
所属仓库
markosAMO/Alfred
最近更新
2026-10-13
Stars
★ 0
Forks
0

01 前言 Front Matter

mode
auto
name
review
next
[ "archive" ]
agent
separate_from_author
skippable
false

03 SKILL.md 正文

review

Answer one question: is this code sound?

Not whether it satisfies the specification. verify established that, and repeating it here spends a review on work already done.

Before reviewing

recall each type the workflow declares, for what the last review of this area said

A should fix nobody fixed is worth raising again, and raising it as a repeat is worth more than raising it as new: the second time it appears it is a pattern rather than a nit, and the reader can see it was already declined once.

This recall is why archive writes those findings. Without it they were written on every change and read on none.

Findings that the change under review has since fixed are dropped silently. Reporting a finding as outstanding when the code no longer has it is how a review loses its credibility.

Runs alongside verify

Dispatched at the same time as verify. Neither reads the other's report and neither writes code, so they cannot interfere.

Do not wait for the verification result, and do not assume it. A review is about whether the code is sound, which does not change based on whether a scenario passed.

A separate agent

This phase runs in a context that never saw the code being written. The agent that wrote it cannot review it: the reasoning that produced a mistake is the reasoning that would have to catch it, and it already agreed with itself once.

The model is at least as strong as the one that implemented, per docs/models.md. A reviewer weaker than the implementer approves everything, and the phase becomes ceremony.

What it reads

the diff of the change
conventions, architecture
the design artifact, and the apply artifact for what changed and what was run

The design is read to know what was intended, including its Out of scope section. Work deliberately excluded is not reported as missing.

What it looks for

conventions      does it follow docs/code_conventions.md
correctness      error handling, edge cases, resource cleanup, concurrency
call sites       does the new contract hold for every caller that already exists
simplicity       is there a materially simpler shape with the same behaviour
duplication      does this already exist in the codebase
coupling         does it reach past the boundaries the architecture draws
security         input handling, authorisation, secrets, injection surfaces
readability      will this be understood by someone who was not here

call sites is the one that needs looking up rather than reading. A modified signature, a changed return type, a helper whose accepted input narrowed: the diff shows the change and not the twelve places that depend on it. Trace them.

changed    helper accepts a string
callers    one worker passes a symbol
result     a regression that passes its own author's tests

verify asks whether the tests reach the real callers. This phase asks whether the callers still work, which is a different question and is answered by reading them.

Severity

Every finding carries one, because a report where everything matters equally is a report nobody acts on.

blocking     ships a defect, a security hole, or violates the architecture
should fix   real problem, does not have to stop this change
suggestion   preference, taste, or a possible future improvement

Only blocking findings stop the change. A phase that blocks on preferences trains the user to skip the phase.

Findings

A finding names the file, the line, what is wrong, and what happens as a result.

### blocking · app/controllers/auth_controller.rb:42
The OAuth state parameter is not compared before creating the session.
A forged callback creates a session for an account the caller does not control.

A finding without a consequence is an opinion. If the consequence cannot be stated, the finding is a suggestion at most.

Rewriting the code is not this phase's job. Findings describe the problem; apply fixes it.

Conventions that were never written

Some findings are real but have no rule behind them: the code works, follows every written convention, and still is not how this team writes code.

Report those as a proposed addition to docs/code_conventions.md, not as a defect.

### convention · app/services/payment_service.rb:18
Errors are returned as result objects here, while the rest of the codebase raises.
Neither is in code_conventions.md.
Proposed: state which one this repository uses.

They never block. archive carries them to memory like any other non-blocking finding, and the user decides whether they become a rule.

This is how the conventions file fills in with what was only ever in someone's head. A convention that exists only as taste produces the same review finding every time and is never fixed, because there is nothing to fix it against.

What it does not do

No re-verification of scenarios. No new requirements. No style rewrites that docs/code_conventions.md does not ask for.

Reviewing code the change did not touch produces findings nobody asked for and buries the ones about the change.

What it writes

## Result
## Blocking
## Should fix
## Suggestions

Failing

Blocking findings return the change to apply with the findings attached. Only the tasks owning the affected files are re-dispatched.

should fix and suggestion findings are recorded and do not block. archive carries them into memory under alfred/area/{area}/review-findings, which this phase recalls on the next change touching that area — see Before reviewing.

A second pass

A review that follows a fix round reads the diff of the fix, not the diff of the change.

The rest of the code was reviewed once, by this phase, and has not changed since. Reading it again produces the same findings, which were either acted on or recorded as should fix and deliberately left — and re-reporting something the user decided to leave is how a report stops being read.

Two things stay whole. The blocking findings of the previous pass are checked as resolved, each against the code that now stands rather than against the claim that it was fixed. And a fix that touched a file outside its own task pulls that file into this pass, because a fix that spread is exactly the case a narrow read would miss.

A second pass

A review that follows a fix round reads the diff of the fix, not the diff of the change.

The rest of the code was reviewed once, by this phase, and has not changed since. Reading it again produces the same findings, which were either acted on or recorded as should fix and deliberately left — and re-reporting something the user decided to leave is how a report stops being read.

Two things stay whole. The blocking findings of the previous pass are checked as resolved, each against the code that now stands rather than against the claim that it was fixed. And a fix that touched a file outside its own task pulls that file into this pass, because a fix that spread is exactly the case a narrow read would miss.

Completion

Follow skills/_shared/phase-protocol.md: write the artifact with its ## Handoff, update state, notify phase_completed or error.

review: 0 blocking, 2 should fix, 3 suggestions

04 同仓库更多 Skills