Vibe Review

Review a target as a gate before the next workflow step. Decide what blocks progress, what is only a suggestion, and what evidence supports the decision.

Rules

• Write review prose in the user's language; keep paths, commands, code, IDs,

status values, labels, and quotes unchanged.

• Keep required template headings, field labels, tables, and status values

exactly as shown for validator compatibility; localize placeholder prose and all human-readable explanatory content to the user's language or the source artifact's primary language.

• Declare Target in every saved review or structured review response.
• Lead with findings. Keep summary and rationale brief.
• Separate Blocking findings from Suggestion findings.
• Do not mark a target ready or passed while blocking questions or blocking

defects remain.

• Ground findings in inspected files, diffs, specs, test evidence, commands, or

explicit user requirements.

• Prefer concise, evidence-first findings over broad advice.
• Use the shared design-quality checks when they explain real risk:

改动扩散, 规则重复, 理解成本, 边界不清, 空壳接口, and 绕路补丁. Do not use them as abstract labels without concrete file, section, behavior, or command evidence.

• Ask only when the missing answer can change the review target, gate decision,

safety, privacy, public contract, or next workflow step.

Workflow

1. Identify The Target

Infer the review target from the user request and artifacts:

• spec: feature spec readiness before vibe-plan.
• code diff or PR: changed code, tests, docs, and commit readiness risk.
• docs/workflow: instructions, plans, evidence, handoffs, or process docs.

If multiple targets apply, review the target that gates the next requested step first. State any skipped target as residual risk.

2. Load Required Context

Before reviewing:

1. Read the target completely.
2. Read applicable repository instructions such as AGENTS.md.
3. Read related spec, review, plan, or test evidence when they define the

target's contract.

1. For Vibe specs, run the Vibe spec validator when the file is available.
2. Read only the rubric for the current target:

- spec: [references/spec-review-rubric.md](references/spec-review-rubric.md) - code diff or PR: [references/code-review-rubric.md](references/code-review-rubric.md) - docs/workflow: [references/workflow-review-rubric.md](references/workflow-review-rubric.md)

Use tools until the review has enough evidence. Do not keep searching once the blocking decision and important risks are clear.

3. Review By Target

For spec, decide whether implementation planning can begin without hidden product, architecture, validation, or rollout decisions.

For code diff or PR, prioritize bugs, regressions, contract mismatches, stale public docs or docstrings, missing tests, sensitive-data exposure, generated-file drift, and violations of the related spec or plan.

For docs/workflow, review whether the artifact is internally consistent, actionable, routed to the right skill or reference, and aligned with the repository workflow.

4. Classify The Gate

Use conclusion labels by target:

• spec: Ready For Development, Needs Revision, or Blocked.
• code diff / PR: Passed, Changes Requested, or Blocked.
• docs/workflow: Passed, Changes Requested, or Blocked.

Use Blocked when an external decision, missing artifact, failed prerequisite, or unavailable evidence prevents a meaningful review.

Classify findings:

• Blocking: the next workflow step should not proceed until resolved.
• Suggestion: improves clarity, quality, or confidence, but does not block.

For each finding, name the exact file, section, line, rule, behavior, or command that makes it actionable.

5. Produce The Review

Use [references/review-template.md](references/review-template.md) for saved artifacts unless the user requests a different format. For code/diff reviews, keep the findings first and keep the change summary secondary.

In OpenSpec mode, use the user-specified change/path or the directory containing the input artifact as the current change directory. If neither identifies it, ask before writing. Save review.md there; if it exists, update it only when explicitly requested. Record the change ID and current artifact path; do not move or archive the change.

The review must include:

1. Blocking Items
2. Suggested Additions
3. Conclusion
4. Effort Estimate
5. Validation Notes
6. Residual Risk

Validation

If you save a review artifact, validate it with:

python3 skills/vibe-review/scripts/validate_review.py path/to/review.md

For in-chat reviews, mentally check that the target is declared, findings lead, the conclusion is target-appropriate, and no blocking finding is hidden in suggestions or residual risk.

Skill Signature

Always end the final response with:

Vibe Skill Signature
Skill: vibe-review
Status: Completed | Passed | Failed | Blocked | Partial
Next: concise next workflow step