# ✅ Keys & Quills – Layered Code Review Checklist
*A structured approach to clear, maintainable, and thoughtful code.*

## 🟣 Layer 1: Surface Integrity
“Can I read this? Does it run? Is it consistent?”

- [ ] Code runs and passes basic tests
- [ ] Syntax is clean (linted and formatted)
- [ ] Naming is clear and descriptive
- [ ] Structure and file placement follow convention
- [ ] Formatting aligns with project style
- [ ] CI/CD or pre-commit hooks catch these automatically

## 🔵 Layer 2: Clarity & Intent
“What is this trying to do, and how clearly does it say it?”

- [ ] Purpose is immediately clear
- [ ] Comments are helpful and explain **why**
- [ ] Logic flows cleanly and reads well
- [ ] Cognitive load is low
- [ ] Code will make sense to future readers

## 🟢 Layer 3: Abstraction & Boundaries
“How does this fit into the rest of the system?”

- [ ] DRY applied judiciously—abstractions make sense
- [ ] Each unit has a single responsibility
- [ ] Consistent levels of abstraction
- [ ] Modular and extensible structure
- [ ] Avoids dumping-ground folders (`utils/`, `helpers/`)
- [ ] Imports are minimal and relevant
- [ ] No circular dependencies
- [ ] Connascence is minimized and explained ([connascence.io](https://connascence.io))
- [ ] Complexity is considered (cyclomatic paths, readability)

## 🟡 Layer 4: System Impact
“What happens when this is deployed?”

- [ ] Dependencies are minimal and stable
- [ ] Code is resilient to change
- [ ] Code is testable and tested
- [ ] Performance is appropriate
- [ ] Security checks (input validation, escaping, auth)
- [ ] Error handling is user-friendly
- [ ] Documentation is updated

## 🟠 Layer 5: Communication & Context
“Does the reviewer understand not just what changed—but why it matters?”

- [ ] PR/commit message explains **intent**
- [ ] Commentary highlights value, tradeoffs, or risks
- [ ] Stakeholders could understand the goal
- [ ] Uncertainty is surfaced for discussion

## 🌱 Self-Check
- [ ] My comments focus on **code**, not the **coder**
- [ ] I gave feedback with **curiosity**
- [ ] I added value, not just criticism
- [ ] I made the **impact and ROI** of this clearer
- [ ] I'd be glad to receive this review myself

[keysandquills.com](https://keysandquills.com)