> workflow / code-review
Code Review
Human-accountable PR review of AI-assisted changes for correctness, security, and maintainability — AI assists; it does not approve.
What should I do next?
Complete the steps and evidence below, clear the human gates, then continue to Testing.
When to use
- A PR exists for an approved plan slice
- Hooks and CI are green or failures are explained
- You need severity-calibrated findings before merge
- Security-sensitive paths changed and need an explicit pass
Step-by-step
- Read the plan item and ADR links before the diff — reject unplanned scope.
- Run code-review.skill / reviewer pattern over the PR; triage severity.
- Use security-review.prompt as a supporting pass on auth, data, and tool surfaces.
- Verify tests prove the behavior claimed; demand gaps be fixed in-slice.
- Check for prompt-injection and secret leakage in new agent/tool code.
- Approve, request changes, or escalate — human reviewer is accountable.
- Capture durable learnings (patterns, anti-patterns) when review finds systemic issues.
Decisions to make
- Approve vs request changes vs hard block for security
- Whether findings are slice bugs vs new architecture debt tickets
- When to require a second reviewer (privileged paths)
- Waiver with expiry vs fix-forward before merge
Evidence to collect
- Review comments with severity and resolution
- Human approval (not bot-only) on the PR
- Security review notes when risk tier requires them
- CI + hook status at approval time
Role-specific next actions
- PM: Ensure merged work still maps to the plan item customers care about.
- Architect: Review boundary and contract changes personally on platform PRs.
- Engineer: Respond to findings with fixes or justified pushback — no silent dismissals.
- Security: Own review on privileged, data-exfil, or tool-allowlist changes.
Inputs
- Pull request and diff
- Plan item + ADR references
- Test and hook results
Outputs
- Review findings and dispositions
- Approval or change request
- Optional knowledge-capture notes
Required prompts
- Security review
Supporting pass — AI-specific and classic vuln surfaces on the diff.
- Knowledge capture
Optional: promote recurring review findings into skills/docs.
Required skills
- Code review
Primary skill for PR review quality and severity calibration.
- Security
Deepens security-sensitive PR review.
Required MCP servers
- GitHub MCP
Fetch PR diffs, comments, and check status in review workflows.
Tooling & handbook
- PR review with AI
How humans use AI assistance without ceding accountability.
- pre-review hook
Prep checklist before human review.
- Reviewer pattern workflow
Operational reviewer workflow.
- Code quality standard
Merge bar.
- Quality checklists
Review checklists by domain.
Recommended agents & patterns
- Reviewer pattern
Primary pattern for this stage.
- Reviewer agent
Drafts findings; human approves merge.
- Security agent
Supporting security pass on sensitive PRs.
Human approval gates
- Human reviewer is accountable — AI review is assistive only
- Four-eyes on privileged paths and production config
Automation opportunities
- CI static analysis and secret scanning required green
- Cookbook/stack review prompts for idiomatic issues
- Block merge when plan item ID is missing from PR template
Enterprise best practices
- Document waivers with owner and expiry
- Retain review evidence for regulated changes
- Separate author and approver on high-risk PRs
Common mistakes
- Trusting AI review as the sole gate
- Reviewing only the diff, not behavior and tests
- Confusing this stage with plan approval (human-review)