SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsverify-workflow-review

verify-workflow-review

Testing & quality

View repository

Updated 10-16 10:04

About this skill

Review — Artifact Review

Entry/Exit

  • Entry: Artifacts that are complete and ready to enter formal review (code, documents, articles, decks, visual designs) or changes about to be merged/delivered
  • Exit: docs/features/<name>/04-review.md Review report
  • Points to: Pass → ship-workflow-ship; issues → return to build for fixes and re-review
  • Output path: → ship-workflow-ship
  • Preload: CANON.md

When not to use

  • The artifact is still in the private draft stage and is not yet ready to enter formal review
  • An equivalent two-stage review report already exists, and it includes Spec Compliance, quality assessment, and verification evidence

Iron Law

Agent Dispatch Contract

/review They are divided into three tiers by independence; the stage order cannot be changed by persona selection.

  • trivial exemption: Limited to tiny changes that are single-file, pure copy/formatting/comments, or mechanical renames, with no UI/security/schema/public API risk; the current agent is allowed to complete both stages, but must record in 04-review.md Record Exemption reason
  • standard: Stage 1 may be performed by the current agent or agents/review-spec-compliance-auditor.md ; Stage 2 must be performed by an independent reviewer persona corresponding to artifact_type (software → agents/review-code-quality-auditor.md）
  • high-risk/full: Stage 1 must be performed by agents/review-spec-compliance-auditor.md ; Stage 2 must be performed by an independent reviewer persona corresponding to artifact_type (software → agents/review-code-quality-auditor.md）
  • If the current session has served as implementer in this feature's /build , then except for trivial exemption , it cannot complete both Stage 1 and Stage 2 at the same time
  • Stage 1 Spec Compliance: must load verify-workflow-spec-compliance
  • Stage 2 Artifact Quality: executed after Stage 1 passes;software must load verify-quality-code-quality
  • document / article 's Stage 2 is by default executed by an independent agents/review-content-auditor.md Execute
  • deck 's Stage 2 is by default executed by an independent agents/review-content-auditor.md ; when page hierarchy, information density, layout, or on-screen readability is involved, additionally add an independent agents/review-visual-auditor.md
  • visual 's Stage 2 is by default executed by an independent agents/review-visual-auditor.md Execute
  • Security-sensitive additions agents/review-security-auditor.md; uncertain test coverage additions agents/review-test-engineer.md; UI/a11y risk additions agents/review-accessibility-auditor.md
  • Unselected reviewers do not produce placeholder feedback; all selected reviewers output Blocking / Important / Suggestion
  • Reviewer personas are read-only by default, and output must be compressed; returning raw logs, full diffs, large code blocks, long reasoning, or irrelevant background is prohibited
  • When large diffs, test logs, or specialized risks would pollute the main session, prioritize dispatching the corresponding reviewer subagent to summarize; the main session only merges conclusions, evidence, file line numbers, risks, and next steps

Process

Step 1: Understand the context

Before looking at the artifact, understand the intent: what is the change meant to achieve? Which part of the spec/plan does it correspond to? What is the expected behavior or change in reader judgment?

Step 2: Look at the primary verification evidence first

  • software: Tests reveal intent and coverage; are there tests? Do they test behavior rather than implementation details? Are boundaries covered? If the code changes, can the tests catch regressions?
  • Non-software: previews, export results, cited sources, and before/after comparisons reveal whether the artifact actually holds up; do not force software's testing semantics onto content or visual artifacts.

Step 3: Two-stage review

First read the spec's artifact_type：

  • software(default) → run two-stage review
  • document / article → load verify-content-review
  • deck → load verify-content-review, and by default check whether verify-visual-review
  • visual → load verify-visual-review

Then determine the independence tier:

  • trivial exemption: must satisfy all conditions of the Agent Dispatch Contract, and record the exemption reason
  • standard: default tier
  • high-risk/full: sensitive data, authentication and authorization, UI/a11y, public API, schema/migration, pre-release review, or user-specified --full

Step 3.1: Spec Compliance (first gate)

REQUIRED SUB-SKILL: verify-workflow-spec-compliance

Check: Is every spec requirement implemented? Does every acceptance criterion have corresponding evidence? Is there scope creep?

Exit: all spec requirements have corresponding implementations, with no Blocking omissions. If not passed → return to build,do not enter Step 3.2。

Step 3.2: Artifact Quality (second gate)

Prerequisite: Step 3.1 passed.

REQUIRED SUB-SKILL:

  • software → verify-quality-code-quality
  • document / article → verify-content-review
  • deck → verify-content-review; if visual hierarchy, layout, or readability would affect the conclusion, additionally add verify-visual-review
  • visual → verify-visual-review

software Execute the five-axis review: Correctness / Readability / Architecture / Security / Performance. For detailed standards, see verify-team-code-review-standards. Non-software artifacts undergo content or visual quality review respectively, and must explicitly cite preview, export, or source evidence. Pre-review / implementation gate results produced during the build phase can only serve as input clues and cannot replace the formal Stage 1 / Stage 2 evidence of this phase.

Step 4: Classify feedback

Prefix Meaning Requirement
No prefix Must change Must be handled before merge
Critical: Blocks merge Security vulnerabilities, data loss, functional crashes
Nit: Optional Style preference, ignore
Consider: Suggested Worth doing but not mandatory
FYI For reference only No action needed

Step 5: Verify the verifier

Check the submitter's verification evidence:

  • software: What tests were run? Did the build pass? Were UI changes screenshotted? Before-and-after comparison?
  • Non-software: What previews were viewed? What final files were exported? What sources, references, dimensions, hierarchy, or export results were checked?

Step 5.2: Check review independence

In 04-review.md explicitly record:

  • Built by
  • Stage 1 reviewed by
  • Stage 2 reviewed by
  • Independence status
  • Exemption reason

Decision rules:

  • PASS: satisfies the requirements of the current independence tier
  • FAIL: standard or high-risk changes did not satisfy the independence requirements
  • EXEMPT: matches trivial exemption, and the reason is specific and auditable

Step 5.5: Check fulfillment of the documentation contract

If 01-spec.md 's Documentation Impact declares project_truth_changed: yes or doc_intent != feature_only：

  • Check whether 03-plan.md contains Project Doc Sync Plan
  • Check whether the affected project-level documentation has been updated, or whether there is an explicit reason for deferral
  • In 04-review.md write Documentation Compliance
  • Required project docs updated: FAIL , the overall verdict cannot be APPROVED

Two review modes

Standard mode (default)

Execute the two-stage review according to the independence tier. For standard changes, by default the current agent executes Stage 1, and then an independent reviewer persona executes Stage 2. Produces docs/features/<name>/04-review.md。

Parallel divergence mode (high-risk --full)

Sensitive data, UI changes, changes over 50 lines, or --full dispatch an independent Spec / Quality / specialist reviewer. For detailed rules, see review-guidance.md。

High-Noise Review Mode

When the diff, test logs, build logs, or artifacts are too large, dispatch a reviewer subagent to read only a compressed version:

  • Large diff: only look at the relevant file diffs and necessary context, do not return the full diff
  • Test failure: only return the failure summary, most likely cause, relevant files, and suggested fix path; do not return the full log
  • Specialized risk: only return Blocking / Important / Suggestion, with evidence and file line numbers

The main session must deduplicate when merging, and must not write the subagent's process analysis into 04-review.md。

Review Standards

Approve: The change clearly improves overall code health, even if imperfect. For detailed guidelines, see review-guidance.md。

Handling Review Disagreements

When the reviewer and the author disagree: technical facts > style guide > design principles > codebase consistency.Do not accept "clean up later" — require cleanup before merge, unless it is truly urgent.

Handling Verification Failures

Failure Scenario Handling Method
Critical issue unresolved Block merge, send back to build for fixes and re-review
Reviewer and author disagree Adjudicate according to the disagreement hierarchy
Change too large (over 1000 lines or content/visual artifact volume cannot be well reviewed in a single pass) Require splitting into multiple PRs / delivery packages
Author refuses to make changes Escalate to the technical lead
software testing is insufficient Require adding boundary/error path tests before re-review
Insufficient evidence for non-software verification Require completing previews, export results, cited sources, or before-and-after comparisons
Independence not satisfied 04-review.md Mark as FAIL, assign an independent reviewer, and re-review
spec requires syncing project docs but it was not fulfilled Block merge; sync the docs before returning to build or ship, and re-review

Common Excuses

Excuse Reality Consequence
"It runs, that's enough" Code that runs but is unreadable/unsafe/architecturally wrong creates compounding debt. Modifying the same module 6 months later balloons from 1h to 1 day
"AI-generated code is probably fine" AI code needs more review, not less. AI bugs are highly hidden; the online failure rate of unreviewed AI code is 2-3x higher
"It passed tests, so it's good" Tests do not catch architecture/security/readability issues; for non-software work even more so, "it can export" cannot replace quality review. Security vulnerabilities, logic breaks, or visual issues will continue to accumulate after formally "passing"
"Clean up later" Later will never come. 90% of code merged into the main branch will never be actively cleaned up

Violating the letter of the rule is violating the spirit. There is no gray area.

Red Flags

  • Artifacts merged / delivered without review
  • Skip Spec Compliance and go directly to Code Quality
  • Conduct quality review when functionality is incomplete
  • Review only checks whether tests pass or files can be opened (ignoring other dimensions)
  • LGTM without actual review evidence
  • Security-sensitive changes have no security review
  • PR or delivery package is too large to review well (require splitting)
  • Bug fix PR has no regression tests
  • Review comments have no severity labels
  • Accept "clean up later"
  • The spec says to sync project docs, but 04-review.md does not have Documentation Compliance
  • Standard changes are completed by the build implementer alone across the two formal review phases

Verification Checklist

  • Understand the intent of the change
  • Spec Compliance review has been performed (phase one)
  • After Spec Compliance passes, Code Quality review has been performed (phase two)
  • For non-software artifacts, content/visual review skills have been loaded according to artifact_type
  • Blocking issues have been resolved
  • software Tests pass, or non-software preview / export / source evidence is sufficient
  • Build succeeded
  • Review Scope clearly states the actual review scope and uncovered scope
  • Evidence Reviewed records tests, build, preview, export, or manual verification evidence
  • Findings Detail includes evidence, impact, fix requirements, and re-review status
  • Resolution & Re-review records fixed/deferred issues and re-review evidence
  • Residual Risk records acceptable risks and follow-up owner
  • Review independence has been recorded; the independent reviewer requirement is met when there is no trivial exemption
  • The documentation synchronization contract has been checked; when project docs need to be synced, it has been written Documentation Compliance
  • The verification story has been recorded
  • Review output is saved to docs/features/<name>/04-review.md

Output Template

After the review is complete,04-review.md must include:

Template Starting Point:templates/feature/04-review.md

# [功能名称] — Review

## Artifact Type
artifact_type: [software/document/article/deck/visual]

## Review Scope
- Reviewed artifacts:
- Reviewed files:
- Reviewed commands / evidence:
- Not reviewed:
- Scope exclusions:

## Review Independence
- Built by: [session / agent / person]
- Stage 1 reviewed by: [session / agent / person]
- Stage 2 reviewed by: [session / agent / person]
- Independence status: PASS / FAIL / EXEMPT
- Exemption reason: [specific reason or n/a]

## Stage 1: Spec Compliance
- Status: PASS / FAIL
- Spec path:
- Coverage: [X/Y] requirements covered
- Acceptance criteria covered:
- Scope creep check: PASS / FAIL
- Unverified requirements: [list or none]
- Blocking gaps: [list or none]

## Stage 2: Artifact Quality (if Stage 1 PASS)
- Quality gate result: PASS / FAIL
- Reviewer assignment:
- Specialist reviews required:
- Specialist reviews completed:
- software:
  - Correctness:
  - Readability:
  - Architecture:
  - Security:
  - Performance:
- document / article / deck:
  - Audience Fit:
  - Logic:
  - Accuracy:
  - Voice:
  - Completeness:
- deck / visual:
  - Hierarchy:
  - Grouping / Alignment:
  - Readability:
  - Export Quality:

## Evidence Reviewed
| Evidence | Source | Result | Notes |
|----------|--------|--------|-------|
| test/build/preview/export/manual/source | command/path/url | PASS / FAIL / n/a | notes |

## Findings Summary
| # | Severity | Category | Description | File:Line | Status |
|---|----------|----------|-------------|-----------|--------|
| 1 | Blocking | Security / Content / Visual | Description | path:line | Open |

## Findings Detail
### #1 — Severity: Title
- Category:
- Location:
- Evidence:
- Impact:
- Required fix:
- Status:
- Re-review result:

## Documentation Compliance
- Feature artifact chain complete: PASS / FAIL
- Project doc sync required by spec: yes / no
- Required project docs updated: PASS / FAIL
- Missing sync: [list or none]

## Resolution & Re-review
- Fixed findings:
- Deferred findings:
- Re-review owner:
- Re-review evidence:

## Residual Risk
- Accepted risks:
- Why acceptable:
- Follow-up owner:
- Tracking:

## Verdict
- Decision: APPROVED / APPROVED_WITH_CONCERNS / REJECTED
- Blocking issues: [count]
- Important issues: [count]
- Merge / ship condition: [all Blocking resolved + accepted Important risk only]
- Blockers remaining:
- Next command: `/ship` / `/build` / `/review`

Post-Review Feedback Handling

After the review is complete, when implementing feedback, refer to the verify-workflow-receiving-review skill to ensure the feedback is correctly understood, classified, and implemented.