Code Quality

Systematic code improvement through review, refactoring, and debugging with verification gates.

Module Selection

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:

1. Get SHAs: BASE_SHA=$(git rev-parse HEAD~1), HEAD_SHA=$(git rev-parse HEAD)
2. Run /code-review, passing: WHAT, PLAN, SHAs, DESCRIPTION
3. Fix Critical immediately, Important before proceeding, note Minor

Verification Gates

Claim a result only after running the command that proves it in this session and reading its output — a claim without that evidence is a guess.

Gate: IDENTIFY → RUN → READ → VERIFY → THEN claim

Review findings (yours or a subagent's) need four more checks before you report them:

1. Guard: Name the guard you searched for on the same path, and say why it does not stop the bug.
2. Intent: Search .okf/ and other project docs for the behavior. Documented as intended → a policy question, not a bug.
3. Origin: Before you blame a commit, run git log -S or git show <sha>^:<file>. Do not infer old behavior from a commit message.
4. Lines: Cite line numbers you read from the file, not from an agent summary.

Refactoring

Mindset

Simplify relentlessly. Preserve behavior religiously. Measure everything.

Every refactoring: small and safe, tested immediately, measurably better.

Protocol

1. Assessment - Baseline metrics, identify smells, classify debt
2. Safety Net - Verify test coverage, add characterization tests
3. Red-Green-Refactor - Write failing test, minimal pass, improve design
4. Pattern Application - SOLID, design patterns, functional transforms
5. Validation - Measure improvements, verify behavior preserved

Code Smells (5 Categories)

1. Bloaters: Long Method, Large Class, Long Parameter List
2. OO Abusers: Switch Statements, Temporary Field
3. Change Preventers: Divergent Change, Shotgun Surgery
4. Dispensables: Duplicate Code, Dead Code, Lazy Class
5. 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 protocols
• references/requesting-code-review.md - Request process
• references/verification-before-completion.md - Verification gates

Refactoring

• references/oop-refactoring-catalog.md - Martin Fowler's patterns
• references/functional-refactoring-patterns.md - FP transformations
• references/code-smells-reference.md - 23 smells, 5 categories
• references/testing-strategies.md - Characterization tests, TDD

Debugging

• references/systematic-debugging.md - Four-phase framework
• references/root-cause-tracing.md - Call stack analysis
• references/defense-in-depth.md - Multi-layer validation
• references/verification.md - Verification protocols

Bottom Line

1. Review: Technical rigor over social performance
2. Refactor: Small, safe, tested, measurable
3. Debug: Root cause first, fix once
4. Always: Evidence before claims

Verify. Question. Then implement. Evidence. Then claim.