tomevault-io 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?"
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/FIXMEin 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.
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.
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.
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:
## 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.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.