--- name: vibepro-human-review description: Use when reviewing VibePro PR preparation artifacts, deciding whether to proceed, split, add evidence, waive with reason, or block. --- # VibePro Human Review ## Purpose Use this Skill when a human or AI reviewer needs to interpret VibePro PR artifacts. `pr-prepare.json` is the readiness source of truth; the review cockpit is the human control plane. ## When to Use Use this Skill when deciding whether a VibePro-prepared change should proceed, split, add evidence, waive with reason, or block. It applies to PR readiness reviews, merge readiness checks, waiver decisions, and cases where the user asks whether VibePro evidence is enough. ## Review Order 1. Read `.vibepro/pr//pr-prepare.json` `gate_status`. 2. Confirm `gate_status.overall_status`, `ready_for_pr_create`, unresolved Gates, and critical unresolved Gates. 3. If `gate_status.agent_review_instruction` is present, block human approval until the coordinator has authorization to use subagents and then has: - run the listed `vibepro review prepare` commands, - dispatched the generated `parallel-dispatch.md` requests to parallel subagents, - closed/shutdown each review subagent after receiving its result, - recorded each result with `vibepro review record` including Codex/Claude Code subagent provenance and `--agent-closed`, - rerun `vibepro pr prepare` and cleared `gate:agent_review`. If the coordinator runtime cannot spawn subagents, treat that as a blocker or require a human waiver decision. Do not accept manual review records as a substitute for required Codex/Claude Code subagent provenance. 4. Read `.vibepro/pr//decision-index.json` and `.vibepro/pr//evidence-plan.json` when present, especially generated/skipped artifacts and review path references. 5. Open `.vibepro/pr//review-cockpit.html` when it was generated for the selected evidence depth. 6. Read the recommended decision and reason from the cockpit or the JSON readiness summary. 7. Check split lanes and Graphify investigation scope from `split-plan.json` / `split-plan.html` when present. 8. For UI modernization PRs, read `.vibepro/design-modernize//derived-design-system.json`, `design-modernize.json`, and `ds-gate.json`. Confirm that current routes, information architecture, CTA priority, state behavior, and data dependencies are preserved unless the Story/Spec explicitly changes them. 9. For performance-sensitive PRs, read the concise `Performance Evidence` summary in `pr-body.md` if present, then verify the JSON runs under `.vibepro/pr//performance-runs/`. 10. Review next commands and confirm they use `vibepro pr create` before PR creation and `vibepro execute merge` before merge. 11. Copy `human-review.json`, fill the review record, and keep it as the human decision artifact. ## Decision Rules - `proceed`: Use only when `gate_status.ready_for_pr_create=true`, `gate_status.overall_status=ready_for_review`, and the split-plan does not require separation. - `split_pr`: Use when scope is broad, repo-control files are mixed in, or split-plan recommends lanes. - `add_evidence`: Use when required Gates need test, typecheck, integration, E2E, or requirement evidence. - `waive_with_reason`: Use only with a specific reason for non-critical unresolved Gates. Critical unresolved Gates cannot be approved by reason alone. - `block`: Use when Story, Architecture, Spec, security, or Gate evidence is contradictory or insufficient. ## Required Record Fill these fields in `human-review.json`: - `review_record.selected_decision` - `review_record.reviewer` - `review_record.reason` - `review_record.reviewed_at` - `review_record.comments` when needed ## Guardrails - Do not treat `review-cockpit.html` as machine-readable truth; use the JSON sidecars. - Do not treat `scope.status=reviewable` as completion approval. It is PR size/scope guidance only. - Do not approve a PR only from the PR body. The PR body is a concise GitHub decision brief; `pr-prepare.json`, decision/evidence indexes, Gate DAG evidence, and verification artifacts are the review control plane. - Do not use raw `gh pr create`; it bypasses VibePro Gate enforcement and waiver recording. - Do not approve with unresolved Agent Review Gate. Missing, stale, or blocking required roles mean the parallel subagent review workflow has not completed for the current git state. - Do not approve a `pass` review result that lacks Codex/Claude Code parallel subagent provenance and closed lifecycle evidence (`--agent-closed`) when `gate:agent_review` is required. It is a coordinator note, not verified subagent review evidence. - If a waiver is chosen, include the exact waiver reason in `vibepro pr create --allow-needs-verification --verification-waiver `. - Do not approve a performance claim when the comparison says `改善率不明` / `not_comparable`. - Do not accept server-side readiness as evidence for user-perceived readiness. User-perceived metrics need `browser_e2e`, `client_marker`, or `manual_observation`. - Check that snapshot visible, DOM visible, API completed, server ready, and interactive ready are not mixed into one completion condition. - Do not approve UI modernization when `ds-gate.json` is missing, has implicit fallback, or omits DS drift / component role / composition / anti-pattern checks. - Do not approve a generated visual direction just because it looks better. Require evidence that it preserves the existing product workflow and that the implementation follows VibePro-derived DS constraints. ## Common Rationalizations - "The PR scope is reviewable, so it can proceed." Scope reviewability is not completion approval. - "The PR body summarizes the gates, so the JSON is unnecessary." `pr-prepare.json`, decision/evidence indexes, Gate DAG evidence, and verification artifacts are the machine-readable truth. - "A human looked at it, so Agent Review is satisfied." Required Agent Review needs the required subagent provenance and lifecycle closure unless waived outside the gate. - "Only non-critical gates remain, so no reason is needed." Waivers must name the exact reason and cannot cover critical gates. - "The UI looks better, so modernization is acceptable." Preservation of workflow, DS constraints, and regression evidence still matter. ## Red Flags - `ready_for_pr_create` is false, missing, or contradicted by unresolved gates. - Critical unresolved gates are being waived by explanation alone. - Agent Review records are stale, manual-only, missing provenance, or missing `--agent-closed`. - Performance evidence says `not_comparable` or `改善率不明` while the PR claims improvement. - UI modernization lacks DS gate or current workflow preservation evidence. - The reviewer only opened the PR body or HTML and did not inspect JSON sidecars. ## Verification Record the final decision from current `pr-prepare.json`, `decision-index.json`, `evidence-plan.json`, Gate DAG evidence, generated review surfaces, and `human-review.json`. If the decision is proceed, confirm `gate_status.ready_for_pr_create=true`, `overall_status=ready_for_review`, no critical unresolved gates, and no split requirement. If the decision is waive, record the exact waiver reason and affected gates. ## Performance Evidence Review For a PR that claims speed improvement, require: - Metric definition exists in the Story `performanceMetrics[]`. - Runs exist under `.vibepro/pr//performance-runs/*.json`. - before and after use the same `metricId` and `completionCondition`. - p50, p90, max, sample count, and incomplete rate are visible. - `blocked`, `needs_review`, `timeout`, `auth_required`, `resource_unavailable`, or `unknown` runs are retained instead of silently dropped. - DB/server metrics and user-perceived metrics are separate when both matter.