Code Quality
Systematic code improvement through review, refactoring, and debugging with verification gates.
Module Selection
| Need |
Module |
Reference |
| Receive Feedback |
Review |
references/code-review-reception.md |
| Request Review |
Review |
references/requesting-code-review.md |
| Verify Before Claim |
Review |
references/verification-before-completion.md |
| Reduce Complexity |
Refactoring |
references/oop-refactoring-catalog.md |
| Functional Patterns |
Refactoring |
references/functional-refactoring-patterns.md |
| Find Code Smells |
Refactoring |
references/code-smells-reference.md |
| Test Strategies |
Refactoring |
references/testing-strategies.md |
| Investigate Bugs |
Debugging |
references/systematic-debugging.md |
| Trace Root Cause |
Debugging |
references/root-cause-tracing.md |
| Add Validation |
Debugging |
references/defense-in-depth.md |
| Verify Fix |
Debugging |
references/verification.md |
Core Principles
YAGNI, KISS, DRY - Always honor these.
Be honest, be brutal, straight to the point, and be concise.
Technical correctness over social comfort. Verify before implementing. Ask before assuming. Evidence before claims.
Code Review
Receiving Feedback
Pattern: READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
Rules:
- ❌ No performative agreement ("You're right!", "Great point!")
- ❌ No implementation before verification
- ✅ Restate requirement, ask questions, push back with reasoning
- ✅ YAGNI check: grep for usage before implementing suggestions
Sources:
- Human partner → Implement after understanding
- External reviewer → Verify technically before implementing
Requesting Review
When: After major features, before merge, after complex fixes
Process:
- Get SHAs:
BASE_SHA=$(git rev-parse HEAD~1), HEAD_SHA=$(git rev-parse HEAD)
- Dispatch code-reviewer subagent with: WHAT, PLAN, SHAs, DESCRIPTION
- Fix Critical immediately, Important before proceeding, note Minor
Verification Gates
Iron Law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
Gate: IDENTIFY → RUN → READ → VERIFY → THEN claim
Skip any step = lying, not verifying.
Refactoring
Mindset
Simplify relentlessly. Preserve behavior religiously. Measure everything.
Every refactoring: small and safe, tested immediately, measurably better.
Protocol
- Assessment - Baseline metrics, identify smells, classify debt
- Safety Net - Verify test coverage, add characterization tests
- Red-Green-Refactor - Write failing test, minimal pass, improve design
- Pattern Application - SOLID, design patterns, functional transforms
- Validation - Measure improvements, verify behavior preserved
Code Smells (5 Categories)
- Bloaters: Long Method, Large Class, Long Parameter List
- OO Abusers: Switch Statements, Temporary Field
- Change Preventers: Divergent Change, Shotgun Surgery
- Dispensables: Duplicate Code, Dead Code, Lazy Class
- Couplers: Feature Envy, Inappropriate Intimacy
Quick Patterns
OOP: Extract Method, Inline, Replace Temp with Query, Guard Clauses
Functional: Map/Filter/Reduce, Pure Functions, Composition, Immutability
Debugging
Core Principle
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Random fixes waste time and create new bugs.
The Four Techniques
1. Systematic Debugging (references/systematic-debugging.md)
- Phase 1: Root Cause Investigation
- Phase 2: Pattern Analysis
- Phase 3: Hypothesis Testing
- Phase 4: Implementation
2. Root Cause Tracing (references/root-cause-tracing.md)
Trace backward through call stack to find original trigger.
3. Defense-in-Depth (references/defense-in-depth.md)
Validate at every layer: Entry → Business logic → Environment → Debug
4. Verification (references/verification.md)
Run command. Read output. Then claim result.
Quick Reference
Bug → systematic-debugging.md (Phase 1-4)
Error deep in stack? → root-cause-tracing.md
Found root cause? → defense-in-depth.md
About to claim success? → verification.md
Red Flags
Stop if thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see"
- "It's probably X, let me fix that"
- "Should work now" / "Seems fixed"
References
Code Review
references/code-review-reception.md - Response protocolsreferences/requesting-code-review.md - Request processreferences/verification-before-completion.md - Verification gates
Refactoring
references/oop-refactoring-catalog.md - Martin Fowler's patternsreferences/functional-refactoring-patterns.md - FP transformationsreferences/code-smells-reference.md - 23 smells, 5 categoriesreferences/testing-strategies.md - Characterization tests, TDD
Debugging
references/systematic-debugging.md - Four-phase frameworkreferences/root-cause-tracing.md - Call stack analysisreferences/defense-in-depth.md - Multi-layer validationreferences/verification.md - Verification protocols
Bottom Line
- Review: Technical rigor over social performance
- Refactor: Small, safe, tested, measurable
- Debug: Root cause first, fix once
- Always: Evidence before claims
Verify. Question. Then implement. Evidence. Then claim.
1---2name: code-quality3description: Code quality improvement: review, refactoring, debugging. Phases: review feedback, systematic refactoring, root cause debugging, verification. Capabilities: SOLID/DRY compliance, code smell detection, complexity reduction, bug investigation, verification gates. Actions: review, refactor, debug, verify, validate code. Keywords: code review, refactor, debug, SOLID, DRY, code smell, bug fix, root cause, verification, technical debt, extract method, test failure, completion claim. Use when: reviewing code changes, improving code quality, fixing bugs, reducing technical debt, validating before merge/commit.4---5
6# Code Quality
7
8Systematic code improvement through review, refactoring, and debugging with verification gates.
9
10## Module Selection
11
12| Need | Module | Reference |
13|------|--------|-----------|
14| **Receive Feedback** | Review | `references/code-review-reception.md` |
15| **Request Review** | Review | `references/requesting-code-review.md` |
16| **Verify Before Claim** | Review | `references/verification-before-completion.md` |
17| **Reduce Complexity** | Refactoring | `references/oop-refactoring-catalog.md` |
18| **Functional Patterns** | Refactoring | `references/functional-refactoring-patterns.md` |
19| **Find Code Smells** | Refactoring | `references/code-smells-reference.md` |
20| **Test Strategies** | Refactoring | `references/testing-strategies.md` |
21| **Investigate Bugs** | Debugging | `references/systematic-debugging.md` |
22| **Trace Root Cause** | Debugging | `references/root-cause-tracing.md` |
23| **Add Validation** | Debugging | `references/defense-in-depth.md` |
24| **Verify Fix** | Debugging | `references/verification.md` |
25
26---
27
28## Core Principles
29
30**YAGNI, KISS, DRY** - Always honor these.
31
32**Be honest, be brutal, straight to the point, and be concise.**
33
34**Technical correctness over social comfort.** Verify before implementing. Ask before assuming. Evidence before claims.
35
36---
37
38## Code Review
39
40### Receiving Feedback
41
42**Pattern:** READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
43
44**Rules:**
45- ❌ No performative agreement ("You're right!", "Great point!")
46- ❌ No implementation before verification
47- ✅ Restate requirement, ask questions, push back with reasoning
48- ✅ YAGNI check: grep for usage before implementing suggestions
49
50**Sources:**
51- Human partner → Implement after understanding
52- External reviewer → Verify technically before implementing
53
54### Requesting Review
55
56**When:** After major features, before merge, after complex fixes
57
58**Process:**
591. Get SHAs: `BASE_SHA=$(git rev-parse HEAD~1)`, `HEAD_SHA=$(git rev-parse HEAD)`
602. Dispatch code-reviewer subagent with: WHAT, PLAN, SHAs, DESCRIPTION
613. Fix Critical immediately, Important before proceeding, note Minor
62
63### Verification Gates
64
65**Iron Law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
66
67**Gate:** IDENTIFY → RUN → READ → VERIFY → THEN claim
68
69Skip any step = lying, not verifying.
70
71---
72
73## Refactoring
74
75### Mindset
76
77Simplify relentlessly. Preserve behavior religiously. Measure everything.
78
79Every refactoring: small and safe, tested immediately, measurably better.
80
81### Protocol
82
831. **Assessment** - Baseline metrics, identify smells, classify debt
842. **Safety Net** - Verify test coverage, add characterization tests
853. **Red-Green-Refactor** - Write failing test, minimal pass, improve design
864. **Pattern Application** - SOLID, design patterns, functional transforms
875. **Validation** - Measure improvements, verify behavior preserved
88
89### Code Smells (5 Categories)
90
911. **Bloaters:** Long Method, Large Class, Long Parameter List
922. **OO Abusers:** Switch Statements, Temporary Field
933. **Change Preventers:** Divergent Change, Shotgun Surgery
944. **Dispensables:** Duplicate Code, Dead Code, Lazy Class
955. **Couplers:** Feature Envy, Inappropriate Intimacy
96
97### Quick Patterns
98
99**OOP:** Extract Method, Inline, Replace Temp with Query, Guard Clauses
100**Functional:** Map/Filter/Reduce, Pure Functions, Composition, Immutability
101
102---
103
104## Debugging
105
106### Core Principle
107
108**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
109
110Random fixes waste time and create new bugs.
111
112### The Four Techniques
113
114**1. Systematic Debugging** (`references/systematic-debugging.md`)
115- Phase 1: Root Cause Investigation
116- Phase 2: Pattern Analysis
117- Phase 3: Hypothesis Testing
118- Phase 4: Implementation
119
120**2. Root Cause Tracing** (`references/root-cause-tracing.md`)
121Trace backward through call stack to find original trigger.
122
123**3. Defense-in-Depth** (`references/defense-in-depth.md`)
124Validate at every layer: Entry → Business logic → Environment → Debug
125
126**4. Verification** (`references/verification.md`)
127Run command. Read output. Then claim result.
128
129### Quick Reference
130
131```
132Bug → systematic-debugging.md (Phase 1-4)
133 Error deep in stack? → root-cause-tracing.md
134 Found root cause? → defense-in-depth.md
135 About to claim success? → verification.md
136```
137
138### Red Flags
139
140Stop if thinking:
141- "Quick fix for now, investigate later"
142- "Just try changing X and see"
143- "It's probably X, let me fix that"
144- "Should work now" / "Seems fixed"
145
146---
147
148## References
149
150### Code Review
151- `references/code-review-reception.md` - Response protocols
152- `references/requesting-code-review.md` - Request process
153- `references/verification-before-completion.md` - Verification gates
154
155### Refactoring
156- `references/oop-refactoring-catalog.md` - Martin Fowler's patterns
157- `references/functional-refactoring-patterns.md` - FP transformations
158- `references/code-smells-reference.md` - 23 smells, 5 categories
159- `references/testing-strategies.md` - Characterization tests, TDD
160
161### Debugging
162- `references/systematic-debugging.md` - Four-phase framework
163- `references/root-cause-tracing.md` - Call stack analysis
164- `references/defense-in-depth.md` - Multi-layer validation
165- `references/verification.md` - Verification protocols
166
167---
168
169## Bottom Line
170
1711. **Review:** Technical rigor over social performance
1722. **Refactor:** Small, safe, tested, measurable
1733. **Debug:** Root cause first, fix once
1744. **Always:** Evidence before claims
175
176Verify. Question. Then implement. Evidence. Then claim.
aibot88