requesting-code-review

Requesting Code Review

When to invoke

BEFORE invoking code-reviewer agent OR before opening a PR for external review. After implementation completes but before claiming done.

Also invoke this as the mandatory plan-review loop immediately after supervibe:writing-plans saves a plan. In plan-review mode, review the plan artifact itself before atomization, epic creation, or execution.

Expert Operating Standard

Follow docs/references/skill-expert-operating-standard.md: start from source of truth, preserve retrieval evidence, apply scope safety, use real producers with runtime receipts for durable delegated outputs, verify before completion claims, and keep confidence below gate when evidence is partial.

Step 0 — Read source of truth (required)

1. Read the spec/plan that motivated the change
2. Read all modified/created/deleted files (git diff)
3. Run full check (npm run check or project equivalent) — capture output
4. Take screenshots if UI change
5. Include wave status and assignment explanation when the change came from /supervibe-loop --assign-ready or a multi-agent wave

Decision tree

What's the review surface?
├─ Single small change (≤3 files, ≤100 lines) → minimal package (diff + test output)
├─ Feature (multiple files, new concept) → full PR description with What/Why/Test plan
└─ Refactor (preserve-behavior change, broad scope) → full + behavioral evidence (before/after)

Procedure

1. Collect change scope — list every file changed with one-line description
2. Write PR description:

   ## What
   <one sentence>
   
   ## Why
   <one sentence + spec link>
   
   ## Test plan
   - [ ] <verification step 1>
   - [ ] <verification step 2>
   

3. Attach evidence:
   • Test output (verbatim, not summarized)
   • Screenshots for UI
   • Performance numbers (before/after) for perf changes
   • Evidence ledger status for required memory, RAG and codegraph citations
   • Assignment explanation, reviewer independence, and wave/block reasons for multi-agent work
4. Identify reviewer agent — code-reviewer for general, security-auditor for security-sensitive, db-reviewer for DB
5. Score — supervibe:confidence-scoring artifact-type=agent-output (the prepared package)
6. Invoke reviewer with the prepared package

Output contract

Plan-review mode

When the input artifact is a plan, produce a review package with:

• Spec coverage and unresolved questions
• MVP value, anti-bloat check, and explicit approved/deferred/rejected scope
• Architecture fit, PRD decision section need, and unresolved architecture decisions
• Risk-triggered specialist coverage for database, cache, queue, security, API, infrastructure, and frontend areas
• Data storage topology, migration safety, backup, restore, and scaling posture when database risk is triggered
• Cache and queue topology, retry, idempotency, and dead-letter behavior when cache or queue risk is triggered
• API contract readiness, error envelope, compatibility, and idempotency when API risk is triggered
• Security and privacy review for threat model, PII, secrets, permission model, and audit logging
• Observability, release, support, rollback, and incident visibility
• Dependency graph and critical-path sanity
• Task size and atomicity
• Verification coverage, including UI/browser evidence where applicable
• Rollback coverage and risky side effects
• Parallel write-set conflicts
• Worktree suitability for long autonomous runs
• Capability assignment, reviewer independence, and wave serialization/blocker reasons
• Provider-policy safety: no bypass defaults, no hidden background automation, explicit stop/resume/status

Plan-review mode must write a durable artifact using docs/templates/plan-review-template.md, validate it with node scripts/validate-plan-review-artifacts.mjs --file <review-artifact>, and score against confidence-rubrics/plan-review.yaml. Inline notes are diagnostic only. The loop can stop with pass only when the Convergence Ledger shows at least one iteration, zero open critical findings, zero open major findings, an explicit stop reason, and a Next User Decision.

If the plan passes, print:

NEXT_STEP_HANDOFF
Current phase: plan-review
Artifact: .supervibe/artifacts/plans/YYYY-MM-DD-<slug>.md
Next phase: work-item-atomization
Next command: /supervibe-loop --atomize-plan .supervibe/artifacts/plans/YYYY-MM-DD-<slug>.md --plan-review-passed
Next skill: supervibe:writing-plans
Stop condition: ask-before-work-item-atomization
Why: A reviewed plan can become durable atomic work items and an epic.
Question: Step 1/1: atomizing the plan into an epic and child work items?
Choices:
- Continue to atomization - uses the reviewed plan path and `--plan-review-passed`; no execution starts yet.
- Revise the reviewed plan first - returns to `/supervibe-plan <plan-path>` with the review findings.
- Ask for another specialist review - reruns review for the unresolved risk area before atomization.
- Keep reviewed plan and stop - records the passed review without creating work items.
END_NEXT_STEP_HANDOFF

Also print NEXT_USER_ACTIONS[]: continue to atomization, revise reviewed plan first, ask for another specialist review, inspect readiness/blockers, or keep reviewed plan and stop. Do not atomize, create an epic, or execute until the user chooses one action.

If the plan fails review, do not atomize or execute. Return findings and route back to /supervibe-plan <plan-path> for repair.

Returns:

• PR description (Markdown)
• File changes list
• Evidence bundle (test output + screenshots + benchmarks)
• Reviewer agent identified

Guard rails

• DO NOT: open PR without running full project checks
• DO NOT: paraphrase test output ("all tests pass" without showing the output)
• DO NOT: attach incomplete evidence (e.g., one screenshot when feature has 3 states)
• ALWAYS: link to spec/plan in PR description
• ALWAYS: include verification commands user can re-run

Verification

• PR description has What + Why + Test plan
• Test output is verbatim
• All claims in description are supported by evidence

Related

• supervibe:code-review — methodology consumed by reviewer
• supervibe:receiving-code-review — how to handle the resulting feedback
• supervibe:pre-pr-check — runs comprehensive checks before this