​

Code Review Process Guide

1. Review a requested PR commit against repository standards and its originating specification.
2. Respond to each published comment with a fix or evidence-based rebuttal.

​

Publishing a Code Review

$code-review-to-github #68 a08e140
$code-review-to-github #68 a08e140..c3a6e7f

​

Step 1: Validate the Review Target

• Fetch the PR through the GitHub connector.
• Confirm the PR exists and is open.
• Fetch the PR body and conversation comments for explicit spec paths and issue references.
• Resolve the commit or range locally.
• Confirm the reviewed commit belongs to the PR history.

​

Step 2: Build Local Context

• Inspect the diff stat, changed filenames, and targeted hunks.
• Use CodeGraph before manual source reads when code impact or symbol flow matters.
• Read relevant architecture or domain decisions.
• Run focused tests, type checks, linters, or package-specific checks when they increase confidence.

​

Step 3: Run the Two Review Axes

​

Standards Axis Checklist

• Documented standards — Check applicable AGENTS.md, CLAUDE.md, coding guides, ADRs, and design rules. Repository rules override the heuristics below.
• Mysterious Name — A name hides the value or behavior it represents.
• Duplicated Code — The same logic shape is repeated in the change.
• Feature Envy — Behavior mostly manipulates another object’s data.
• Data Clumps — The same fields or parameters repeatedly travel together.
• Primitive Obsession — A domain concept is represented by an unsafe primitive.
• Repeated Switches — Equivalent condition trees recur in multiple places.
• Shotgun Surgery — One behavior change requires scattered edits.
• Divergent Change — One module changes for unrelated reasons.
• Speculative Generality — Abstractions exist for requirements not requested.
• Message Chains — Callers navigate through several internal objects.
• Middle Man — A layer adds delegation without useful policy or behavior.
• Refused Bequest — An implementation inherits a contract it mostly rejects.
• Concrete impact — Report a heuristic only when it creates a specific maintenance or correctness impact in this diff.
• Tooling boundary — Skip formatting or checks already enforced by existing tooling.

​

Find the Specification

1. An exact spec/change path supplied by the user or named in the PR body or comments.
2. Issue references in the reviewed commits, PR body, or comments.
3. A matching OpenSpec change under:
   • backend/go/openspec/changes/
   • backend/bun/openspec/changes/
   • frontend/astro/openspec/changes/
   • frontend/solidstart/openspec/changes/
   • mobile/flutter/openspec/changes/
4. A matching PRD/spec under docs/, specs/, or .scratch/.
5. The PR body, when it contains verifiable requirements.

​

Spec Axis Checklist

• Missing requirements — Identify requirements that are not implemented.
• Partial requirements — Identify requirements that are only partly implemented.
• Contradicting behavior — Identify behavior that conflicts with a requirement.
• Scope creep — Identify behavior outside the requested scope.
• Acceptance failure — Identify implementation that appears present but fails the stated acceptance behavior.
• Requirement citation — Cite the exact requirement for every candidate.
• No inferred requirements — Do not create findings from personal preference.

​

Step 4: Keep Only Actionable Findings

​

Step 5: Anchor Findings to the PR Diff

• Place inline comments only on lines present in the PR diff.
• Prefer changed lines on the right side of the diff.
• Use a multi-line anchor only when the entire range is present.
• Put an unanchorable finding in the review body instead of inventing a line.

​

Step 6: Publish One Review

💡Codex Review
Here are some automated review suggestions for this pull request.

Reviewed commit: a08e140
Standards: 1 finding.
Spec: 2 findings.

[P2] [Spec] Preserve run-on-boot behavior

​

Follow-Up Commits

​

Responding to Review Comments

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

​

Step 1: Identify & Analyze Comments

• Review threads on the PR (inline code comments)
• PR comments section
• Review submissions

• 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

​

Step 3: Take Action

• Fix the code or documentation
• Test the changes
• Note the commit hash(es)

• Gather evidence proving it’s wrong
• Collect file paths and commit references
• Prepare detailed explanation

​

Step 4: Post Response to Thread

✅ FIXED — [What was corrected]

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

Committed in [commit hash].

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

1. Go to the comment thread
2. Click “Resolve conversation”
3. Confirm resolution

​

Example Walkthrough

​

Scenario: Invalid Comment

“Remove premature claim that auth use cases are deleted”

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).

​

Scenario: Valid Comment

“Fix broken cross-doc links”

• Fixed ../go/architecture/authentication → /backend/go/architecture/authentication
• Fixed ../../shared/authentication-flow → /shared/authentication-flow
• Committed in commit 0a10905

✅ 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.

​

Best Practices

• Keep review axes separate — Standards and Spec findings answer different questions
• Respect the requested boundary — Review only the specified commit or range
• Do not invent requirements — Skip the Spec axis when no reliable specification exists
• Publish once per pass — Aggregate all findings into one GitHub review
• 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

​

Related Links

• Pull Request Reviews — Active PRs
• Codex Documentation — About Codex code review bot