Python Code Review
Review Python changes using the Review Pyramid: prioritize what matters, automate what doesn't.
Activation Contract
Apply when the user asks to review changes, a diff, or a PR, or to check code before merge. Reviewing is distinct from writing: focus on judgment, not rewriting.
Hard Rules
- Review bottom-up: API semantics → implementation correctness → docs → tests → style. Spend effort where the pyramid is widest at the base.
- Flag style/nits last and lightest: they are automatable (ruff/formatter), not merge-blockers.
- Always anchor review in task/business context; correctness depends on intent.
- Block on: breaking API contracts, wrong business logic, unhandled edge cases, security issues, missing tests for new behavior.
- Verify claims against the diff: never approve logic you have not traced.
Decision Gates
| Layer |
Check |
Severity |
| API semantics |
Breaking changes, naming, contracts |
Critical |
| Implementation |
Business logic, edge cases, error handling |
Critical |
| Security |
Injection, authz, data exposure |
Critical |
| Tests |
New behavior covered, branch coverage |
High |
| Docs |
Public surface documented |
Medium |
| Style |
Lint/format |
Nit (automate) |
Execution Steps
- Quick pass: lint, type check, security pattern scan, confirm tests exist.
- Deep pass: trace API and implementation semantics against the stated task.
- Check edge cases and error paths; confirm tests cover new branches.
- Report findings ordered by severity (Critical → Nit), each with file:line and a concrete fix.
Output Contract
Return findings grouped by pyramid layer, severity-ordered, each citing file:line with a specific remediation. Separate merge-blockers from nits explicitly. Do not rewrite the change: review it.
References
- Pair with
python-clean-code, python-design-principles, and python-testing-tdd to justify findings.
1---2name: python-code-review3description: Trigger: code review, review my changes, review this PR, check my code, pre-merge review, review diff. Review Python changes by the Review Pyramid, priority-first.4license: Apache-2.05---67# Python Code Review89Review Python changes using the Review Pyramid: prioritize what matters, automate what doesn't.1011## Activation Contract1213Apply when the user asks to review changes, a diff, or a PR, or to check code before merge. Reviewing is distinct from writing: focus on judgment, not rewriting.1415## Hard Rules1617- Review bottom-up: API semantics → implementation correctness → docs → tests → style. Spend effort where the pyramid is widest at the base.18- Flag style/nits last and lightest: they are automatable (ruff/formatter), not merge-blockers.19- Always anchor review in task/business context; correctness depends on intent.20- Block on: breaking API contracts, wrong business logic, unhandled edge cases, security issues, missing tests for new behavior.21- Verify claims against the diff: never approve logic you have not traced.2223## Decision Gates2425| Layer | Check | Severity |26|-------|-------|----------|27| API semantics | Breaking changes, naming, contracts | Critical |28| Implementation | Business logic, edge cases, error handling | Critical |29| Security | Injection, authz, data exposure | Critical |30| Tests | New behavior covered, branch coverage | High |31| Docs | Public surface documented | Medium |32| Style | Lint/format | Nit (automate) |3334## Execution Steps35361. Quick pass: lint, type check, security pattern scan, confirm tests exist.372. Deep pass: trace API and implementation semantics against the stated task.383. Check edge cases and error paths; confirm tests cover new branches.394. Report findings ordered by severity (Critical → Nit), each with file:line and a concrete fix.4041## Output Contract4243Return findings grouped by pyramid layer, severity-ordered, each citing `file:line` with a specific remediation. Separate merge-blockers from nits explicitly. Do not rewrite the change: review it.4445## References4647- Pair with `python-clean-code`, `python-design-principles`, and `python-testing-tdd` to justify findings.
JoseVelazcoH