mirror of
https://github.com/kuhyx/testsAndMisc.git
synced 2026-11-22 05:42:19 +01:00
Twelve prose violations to zero. Eight files split into per-topic subdirectories with the original left as an index; both SKILL.md files keep their frontmatter so discovery still works, with detail moved to references/. Deleted docs/cleanup-2026-05/ (7 files) and linux_configuration/docs/ VERIFICATION.md on the user's ruling: unreferenced records of finished work whose rules are now enforced by the polling, shellcheck and shfmt hooks. PACMAN_WRAPPER_SECURITY.md was split instead - unlike those, it documents live guarantees. Every split verified by a sorted diff against HEAD: zero content lines lost, only the new headings and index links added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
154 lines
6.3 KiB
Markdown
154 lines
6.3 KiB
Markdown
# Dead code hygiene and the review checklist
|
|
|
|
## Dead Code Hygiene
|
|
|
|
After any refactoring or implementation change, check for orphaned code:
|
|
|
|
1. Identify code that is now unreachable or unused
|
|
2. List it explicitly
|
|
3. **Ask before deleting:** "Should I remove these now-unused elements: [list]?"
|
|
|
|
Don't leave dead code lying around — it confuses future readers and agents. But don't silently delete things you're not sure about. When in doubt, ask.
|
|
|
|
```
|
|
DEAD CODE IDENTIFIED:
|
|
- formatLegacyDate() in src/utils/date.ts — replaced by formatDate()
|
|
- OldTaskCard component in src/components/ — replaced by TaskCard
|
|
- LEGACY_API_URL constant in src/config.ts — no remaining references
|
|
→ Safe to remove these?
|
|
```
|
|
|
|
## Review Speed
|
|
|
|
Slow reviews block entire teams. The cost of context-switching to review is less than the waiting cost imposed on others.
|
|
|
|
- **Respond within one business day** — this is the maximum, not the target
|
|
- **Ideal cadence:** Respond shortly after a review request arrives, unless deep in focused coding. A typical change should complete multiple review rounds in a single day
|
|
- **Prioritize fast individual responses** over quick final approval. Quick feedback reduces frustration even if multiple rounds are needed
|
|
- **Large changes:** Ask the author to split them rather than reviewing one massive changeset
|
|
|
|
## Handling Disagreements
|
|
|
|
When resolving review disputes, apply this hierarchy:
|
|
|
|
1. **Technical facts and data** override opinions and preferences
|
|
2. **Style guides** are the absolute authority on style matters
|
|
3. **Software design** must be evaluated on engineering principles, not personal preference
|
|
4. **Codebase consistency** is acceptable if it doesn't degrade overall health
|
|
|
|
**Don't accept "I'll clean it up later."** Experience shows deferred cleanup rarely happens. Require cleanup before submission unless it's a genuine emergency. If surrounding issues can't be addressed in this change, require filing a bug with self-assignment.
|
|
|
|
## Honesty in Review
|
|
|
|
When reviewing code — whether written by you, another agent, or a human:
|
|
|
|
- **Don't rubber-stamp.** "LGTM" without evidence of review helps no one.
|
|
- **Don't soften real issues.** "This might be a minor concern" when it's a bug that will hit production is dishonest.
|
|
- **Quantify problems when possible.** "This N+1 query will add ~50ms per item in the list" is better than "this could be slow."
|
|
- **Push back on approaches with clear problems.** Sycophancy is a failure mode in reviews. If the implementation has issues, say so directly and propose alternatives.
|
|
- **Accept override gracefully.** If the author has full context and disagrees, defer to their judgment. Comment on code, not people — reframe personal critiques to focus on the code itself.
|
|
|
|
## Dependency Discipline
|
|
|
|
Part of code review is dependency review:
|
|
|
|
**Before adding any dependency:**
|
|
|
|
1. Does the existing stack solve this? (Often it does.)
|
|
2. How large is the dependency? (Check bundle impact.)
|
|
3. Is it actively maintained? (Check last commit, open issues.)
|
|
4. Does it have known vulnerabilities? (`npm audit`)
|
|
5. What's the license? (Must be compatible with the project.)
|
|
|
|
**Rule:** Prefer standard library and existing utilities over new dependencies. Every dependency is a liability.
|
|
|
|
## The Review Checklist
|
|
|
|
```markdown
|
|
## Review: [PR/Change title]
|
|
|
|
### Context
|
|
|
|
- [ ] I understand what this change does and why
|
|
|
|
### Correctness
|
|
|
|
- [ ] Change matches spec/task requirements
|
|
- [ ] Edge cases handled
|
|
- [ ] Error paths handled
|
|
- [ ] Tests cover the change adequately
|
|
|
|
### Readability
|
|
|
|
- [ ] Names are clear and consistent
|
|
- [ ] Logic is straightforward
|
|
- [ ] No unnecessary complexity
|
|
|
|
### Architecture
|
|
|
|
- [ ] Follows existing patterns
|
|
- [ ] No unnecessary coupling or dependencies
|
|
- [ ] Appropriate abstraction level
|
|
|
|
### Security
|
|
|
|
- [ ] No secrets in code
|
|
- [ ] Input validated at boundaries
|
|
- [ ] No injection vulnerabilities
|
|
- [ ] Auth checks in place
|
|
- [ ] External data sources treated as untrusted
|
|
|
|
### Performance
|
|
|
|
- [ ] No N+1 patterns
|
|
- [ ] No unbounded operations
|
|
- [ ] Pagination on list endpoints
|
|
|
|
### Verification
|
|
|
|
- [ ] Tests pass
|
|
- [ ] Build succeeds
|
|
- [ ] Manual verification done (if applicable)
|
|
|
|
### Verdict
|
|
|
|
- [ ] **Approve** — Ready to merge
|
|
- [ ] **Request changes** — Issues must be addressed
|
|
```
|
|
|
|
## See Also
|
|
|
|
- For detailed security review guidance, see `references/security-checklist.md`
|
|
- For performance review checks, see `references/performance-checklist.md`
|
|
|
|
## Common Rationalizations
|
|
|
|
| Rationalization | Reality |
|
|
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
|
|
| "It works, that's good enough" | Working code that's unreadable, insecure, or architecturally wrong creates debt that compounds. |
|
|
| "I wrote it, so I know it's correct" | Authors are blind to their own assumptions. Every change benefits from another set of eyes. |
|
|
| "We'll clean it up later" | Later never comes. The review is the quality gate — use it. Require cleanup before merge, not after. |
|
|
| "AI-generated code is probably fine" | AI code needs more scrutiny, not less. It's confident and plausible, even when wrong. |
|
|
| "The tests pass, so it's good" | Tests are necessary but not sufficient. They don't catch architecture problems, security issues, or readability concerns. |
|
|
|
|
## Red Flags
|
|
|
|
- PRs merged without any review
|
|
- Review that only checks if tests pass (ignoring other axes)
|
|
- "LGTM" without evidence of actual review
|
|
- Security-sensitive changes without security-focused review
|
|
- Large PRs that are "too big to review properly" (split them)
|
|
- No regression tests with bug fix PRs
|
|
- Review comments without severity labels — makes it unclear what's required vs optional
|
|
- Accepting "I'll fix it later" — it never happens
|
|
|
|
## Verification
|
|
|
|
After review is complete:
|
|
|
|
- [ ] All Critical issues are resolved
|
|
- [ ] All Important issues are resolved or explicitly deferred with justification
|
|
- [ ] Tests pass
|
|
- [ ] Build succeeds
|
|
- [ ] The verification story is documented (what changed, how it was verified)
|