Code Review Process Guide

​
Code Review Process Guide

This guide documents the workflow for responding to code review comments (e.g., from Codex) on GitHub pull requests.

​
Overview

Every code review comment requires:
  1. Analysis (valid or invalid)
  2. Action (fix or rebuttal)
  3. Response (explanation posted to thread)
  4. Resolution (mark conversation as Resolved)

​
Workflow

​
Step 1: Identify & Analyze Comments

Where to find comments:
  • Review threads on the PR (inline code comments)
  • PR comments section
  • Review submissions
Analysis checklist:
  • Is the comment factually correct?
  • Does it point to an actual issue in the code/docs?
  • Is there evidence to support the claim?
  • Can it be fixed or is it based on incorrect assumptions?

​
Step 2: Determine if Valid or Invalid

Valid CommentInvalid Comment
Points out real bug or issueBased on misunderstanding
Documentation is incorrectCode already has the fix
Best practice violationReferences non-existent code
Legitimate improvementOutdated information about codebase

​
Step 3: Take Action

If VALID:
  • Fix the code or documentation
  • Test the changes
  • Note the commit hash(es)
If INVALID:
  • Gather evidence proving it’s wrong
  • Collect file paths and commit references
  • Prepare detailed explanation

​
Step 4: Post Response to Thread

CRITICAL: Always respond to the comment thread BEFORE marking as resolved. Response format for valid comments: 
✅ FIXED — [What was corrected]

Changes made in:
- [File]: [Description]
- [File]: [Description]

Committed in [commit hash].
Response format for invalid comments: 
This comment is INVALID — [Why it's incorrect]

Evidence:
✅ [Proof 1 with file path]
✅ [Proof 2 with commit reference]
✅ [Proof 3 with code state]

[Explain actual current state of code]

​
Step 5: Mark Conversation as Resolved

After posting your response:
  1. Go to the comment thread
  2. Click “Resolve conversation”
  3. Confirm resolution
Note: Do not resolve without responding first. The response is the audit trail for why the feedback was accepted or rejected.

​
Example Walkthrough

​
Scenario: Invalid Comment

Codex Comment:
“Remove premature claim that auth use cases are deleted”
Analysis: Invalid — use cases were actually deleted in commit d86d832 Response Posted: 
This comment is INVALID — the auth use cases have actually been deleted.

Evidence:
✅ register-user.use-case.ts — DELETED (commit d86d832)
✅ login-user.use-case.ts — DELETED (commit d86d832)
✅ update-user-profile.use-case.ts — DELETED (commit d86d832)
✅ get-user.use-case.ts — DELETED (commit d86d832)
✅ user.repository.ts — DELETED (commit d86d832)

Route handlers now delegate directly to Better Auth APIs (see api.ts).
Then: Mark conversation as Resolved ✅

​
Scenario: Valid Comment

Codex Comment:
“Fix broken cross-doc links”
Analysis: Valid — links use relative paths that don’t resolve Action Taken:
  • Fixed ../go/architecture/authentication → /backend/go/architecture/authentication
  • Fixed ../../shared/authentication-flow → /shared/authentication-flow
  • Committed in commit 0a10905
Response Posted: 
✅ FIXED — Corrected broken cross-doc links

Changes made in backend/bun/docs/architecture/better-auth-user-module.mdx:
- `../go/architecture/authentication` → `/backend/go/architecture/authentication`
- `../../shared/authentication-flow` → `/shared/authentication-flow`

Committed in 0a10905.
Then: Mark conversation as Resolved ✅

​
Best Practices

  • Always provide context — Include file paths, commit hashes, or code snippets
  • Use evidence over opinions — Back up your response with facts
  • Be concise but complete — Explain the decision clearly but briefly
  • Document decisions — The response thread is the audit trail for architectural/review decisions
  • Don’t skip the response — Even if obvious to you, document why the feedback was accepted/rejected