Refining

Refine code changes to make them easy to review.

Philosophy

Why Refine?

Refining exists because reviewers are humans with limited attention.

The core question isn't "what checks should I run?" but "would I want to review this?"

code

The Reviewer's Reality:
├── Context loading takes mental effort
├── Large changes exhaust attention
├── Mixed concerns require mental switching
└── Unclear changes create uncertainty

The Reviewer's Burden

Every code review requires:

•Context loading - Understanding what the change is about
•Verification - Checking if it's correct
•Risk assessment - What could this break?

Small, focused changes make this tractable. Large, mixed changes make it exhausting.

Cohesion Over Size

A 500-line focused change is often easier to review than a 200-line mixed change.

Why?

•Focused changes have one mental model
•Mixed changes require context switching for each concern
•Each concern should be independently verifiable

The "lines changed" heuristic is about cognitive load, not absolute limits. Ask: Could a reviewer hold this entire change in their head?

The Refining Mindset

Before committing or creating a PR, ask:

•Would I want to review this?
•Can I explain this in one sentence?
•If this breaks, is the blast radius obvious?

If yes to all → proceed. If no → refine further.

Core Concepts

Reviewability Factors

Factor	What it measures	Why it matters
Cohesion	Single purpose?	Mental model simplicity
Size	Cognitive load	Reviewer attention span
Clarity	Is intent obvious?	Time to understand
Noise	Distractions present?	Focus degradation

These aren't gates to pass. They're lenses to evaluate through.

When to Split

Not "must split" - but "consider splitting":

•Feature + refactor → Refactor can be reviewed independently
•Bug fix + new feature → Fix is urgent, feature can wait
•Multiple unrelated changes → Each deserves its own commit

The question: Would reviewing these separately produce better feedback?

Noise Detection

Noise makes reviewers work harder without adding value:

•console.log, print, debugger → Should these be here?
•TODO/FIXME in new code → Is this intentional?
•Commented-out code → Dead code or notes?

Note these to the user. Let them decide if intentional.

Three Modes

Commit

Validate staged changes, create commit.

code

1. Check staged:     git diff --cached --stat
2. Assess:           Cohesion? Size? Noise?
3. Generate message: Conventional Commits format
4. Commit:           git commit -m "type(scope): description"

Never push unless explicitly requested.

Review

Assess a PR/MR or branch comparison.

code

1. Identify target:  PR URL, branch, or current changes
2. Quick assessment: Cohesion, size, obvious issues
3. Detailed review:  Focus on what linters miss
4. Report:           Severity-based (🔴 Critical, 🟡 Important, 🔵 Suggestion)

Focus your attention where it matters most. Skip what automated tools catch.

See reference/review-strategies.md for project-specific approaches.

Create PR/MR

Generate reviewer-focused description.

code

1. Gather changes:   git log --oneline main..HEAD
2. Assess:           Is this PR-ready?
3. Generate:         Title + description + context
4. Create:           gh pr create / glab mr create

Description structure:

markdown

## Summary
[What and why in 1-2 sentences]

## Changes
[Key changes as bullet points]

## Testing
[How to verify this works]

## Reviewer Notes
[What to focus on, known risks, trade-offs]

See reference/description-guide.md for examples.

Understanding, Not Rules

Instead of memorizing thresholds, understand the underlying tensions:

Tension	Resolution
Speed vs Quality	Quick changes need less refinement. Critical paths need more.
Completeness vs Focus	Better to have multiple focused PRs than one sprawling one.
Description Detail vs Reader Time	Enough to understand, not encyclopedic.
Stopping Early vs Proceeding	When in doubt, ask. User decides.

On Line Counts

"400 lines" isn't a magic number. It's a heuristic for "about the limit of focused review."

•Simple rename across many files? 1000 lines might be fine.
•Complex algorithm change? 100 lines needs careful review.

Match review depth to change complexity, not line count.

Reference

Load these as needed, not upfront:

•reference/reviewability.md - Detailed criteria
•reference/description-guide.md - PR/MR examples
•reference/review-strategies.md - Approaches by context
•reference/review-checklist.md - Language-specific checks
•reference/impact-analysis.md - Blast radius techniques

The Goal

The goal isn't to follow a checklist. It's to create changes that reviewers can understand quickly and review confidently.

Reviewability is empathy. Put yourself in the reviewer's shoes.