majiayu000 Code Review
Guide proper code review practices emphasizing technical rigor, evidence-based claims, and verification over performative responses.
Core Principle
YAGNI, KISS, DRY always. Technical correctness over social comfort. Be honest, be brutal, straight to the point, and be concise.
Verify before implementing. Ask before assuming. Evidence before claims.
Three Practices
| Practice | When | Reference |
|---|---|---|
| Receiving feedback | Unclear feedback, external reviewers, needs prioritization | references/code-review-reception.md |
| Requesting review | After tasks, before merge, stuck on problem | references/requesting-code-review.md |
| Verification gates | Before any completion claim, commit, PR | references/verification-before-completion.md |
| Edge case scouting | After implementation, before review | references/edge-case-scouting.md |
Quick Decision Tree
SITUATION?
│
├─ Received feedback → STOP if unclear, verify if external, implement if human partner
├─ Completed work → Scout edge cases → Request code-reviewer subagent
└─ About to claim status → RUN verification command FIRST
Receiving Feedback
Pattern: READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
Rules:
- ❌ No performative agreement: "You're absolutely right!", "Great point!"
- ❌ No implementation before verification
- ✅ Restate, ask questions, push back with reasoning, or just work
- ✅ YAGNI check: grep for usage before implementing "proper" features
Source handling:
- Human partner: Trusted - implement after understanding
- External reviewers: Verify technically, check breakage, push back if wrong
Full protocol: references/code-review-reception.md
Requesting Review
When: After each task, major features, before merge
Process:
- Scout edge cases first (see below)
- Get SHAs:
BASE_SHA=$(git rev-parse HEAD~1)andHEAD_SHA=$(git rev-parse HEAD) - Dispatch code-reviewer subagent with: WHAT, PLAN, BASE_SHA, HEAD_SHA, DESCRIPTION
- Fix Critical immediately, Important before proceeding
Full protocol: references/requesting-code-review.md
Edge Case Scouting (NEW)
When: After implementation, before requesting code-reviewer
Purpose: Proactively find edge cases, side effects, and potential issues using scout skill.
Process:
- Invoke
/scoutwith edge-case-focused prompt - Scout analyzes: affected files, data flows, error paths, boundary conditions
- Review scout findings for potential issues
- Address critical gaps before code review
Full protocol: references/edge-case-scouting.md
Verification Gates
Iron Law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
Gate: IDENTIFY command → RUN full → READ output → VERIFY confirms → THEN claim
Requirements:
- Tests pass: Output shows 0 failures
- Build succeeds: Exit 0
- Bug fixed: Original symptom passes
- Requirements met: Checklist verified
Red Flags: "should"/"probably"/"seems to", satisfaction before verification, trusting agent reports
Full protocol: references/verification-before-completion.md
Integration with Workflows
- Subagent-Driven: Scout edge cases → Review after EACH task → Verify before next
- Pull Requests: Scout → Verify tests → Code-reviewer review → Merge
- General: Verification gates before any status claims
Bottom Line
- Technical rigor over social performance
- Scout edge cases before review
- Evidence before claims
Verify. Scout. Question. Then implement. Evidence. Then claim.