tatkhanhgia/ck:code-review

Code Review

Guide proper code review practices emphasizing technical rigor, evidence-based claims, and verification over performative responses.

Default (No Arguments)

If invoked with context (recent changes/PR), proceed with review. If invoked WITHOUT arguments, use AskUserQuestion to present available review operations:

| Operation | Description | |-----------|-------------| | (default) | Review recent changes/PR | | codebase | Full codebase scan & analysis | | codebase parallel | Parallel multi-reviewer audit |

Present as options via AskUserQuestion with header "Review Operation", question "What would you like to do?".

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.

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 | | Task-managed reviews | Multi-file features (3+ files), parallel reviewers, fix cycles | references/task-management-reviews.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
├─ Multi-file feature (3+ files) → Create review pipeline tasks (scout→review→fix→verify)
└─ 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:

1. Scout edge cases first (see below)
2. Get SHAs: BASE_SHA=$(git rev-parse HEAD~1) and HEAD_SHA=$(git rev-parse HEAD)
3. Dispatch code-reviewer subagent with: WHAT, PLAN, BASE_SHA, HEAD_SHA, DESCRIPTION
4. Fix Critical immediately, Important before proceeding

Full protocol: references/requesting-code-review.md

Edge Case Scouting

When: After implementation, before requesting code-reviewer

Process:

1. Invoke /ck:scout with edge-case-focused prompt
2. Scout analyzes: affected files, data flows, error paths, boundary conditions
3. Review scout findings for potential issues
4. Address critical gaps before code review

Full protocol: references/edge-case-scouting.md

Task-Managed Review Pipeline

When: Multi-file features (3+ changed files), parallel code-reviewer scopes, review cycles with Critical fix iterations.

Pipeline: scout → review → fix → verify (each a Task with dependency chain)

TaskCreate: "Scout edge cases"         → pending
TaskCreate: "Review implementation"    → pending, blockedBy: [scout]
TaskCreate: "Fix critical issues"      → pending, blockedBy: [review]
TaskCreate: "Verify fixes pass"        → pending, blockedBy: [fix]

Parallel reviews: Spawn scoped code-reviewer subagents for independent file groups (e.g., backend + frontend). Fix task blocks on all reviewers completing.

Re-review cycles: If fixes introduce new issues, create cycle-2 review task. Limit 3 cycles, escalate to user after.

Full protocol: references/task-management-reviews.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
• Task Pipeline: Create review tasks with dependencies → auto-unblock through chain
• Cook Handoff: Cook completes phase → review pipeline tasks → all complete → cook proceeds

Codebase Analysis Subcommands

| Subcommand | Reference | Purpose | |------------|-----------|---------| | /ck:code-review codebase | references/codebase-scan-workflow.md | Scan & analyze the codebase | | /ck:code-review codebase parallel | references/parallel-review-workflow.md | Ultrathink edge cases, then parallel verify |

Bottom Line

1. Technical rigor over social performance
2. Scout edge cases before review
3. Task-manage reviews for multi-file features
4. Evidence before claims

Verify. Scout. Question. Then implement. Evidence. Then claim.