Technical Debt Patterns

Expert patterns for detecting, categorizing, and prioritizing technical debt in Rails applications.

Decision Tree: Debt Category Identification

What type of issue is this? │ ├─ Code structure problem? │ ├─ Method too long (>20 lines) → Code Smell: Long Method │ ├─ Class too large (>150 lines) → Code Smell: Large Class │ ├─ Excessive parameter passing → Code Smell: Data Clump │ └─ Method uses another object's data → Code Smell: Feature Envy │ ├─ Complexity issue? │ ├─ Flog score >60 → Complexity: High │ ├─ Cyclomatic complexity >10 → Complexity: High │ ├─ Deep nesting (>3 levels) → Complexity: Nesting │ └─ Too many conditionals → Complexity: Conditional │ ├─ Security concern? │ ├─ SQL injection risk → Security: SQL Injection │ ├─ XSS vulnerability → Security: XSS │ ├─ Mass assignment issue → Security: Mass Assignment │ └─ Outdated gem with CVE → Security: Dependency │ ├─ Outdated code? │ ├─ Rails deprecation warning → Deprecation: Rails │ ├─ Ruby version warning → Deprecation: Ruby │ └─ Deprecated gem API → Deprecation: Gem │ ├─ Performance problem? │ ├─ N+1 query pattern → Performance: N+1 │ ├─ Missing database index → Performance: Index │ ├─ Memory bloat → Performance: Memory │ └─ Slow query → Performance: Query │ └─ Architecture violation? ├─ Fat controller → Architecture: Controller ├─ God object/model → Architecture: God Object ├─ Circular dependency → Architecture: Circular └─ Layer violation → Architecture: Layering

NEVER Do These (Critical Anti-Patterns)

NEVER ignore security debt because "we'll fix it later":

WRONG - Ignoring SQL injection

User.where("name = '#{params[:name]}'") # Security debt accumulates risk

RIGHT - Fix immediately or track with Critical severity

User.where(name: params[:name])

→ Security debt has exponential risk growth. Track as Critical, not backlog.

NEVER create technical debt to "fix" technical debt:

WRONG - Adding wrapper to hide complexity

class PaymentWrapper def process @legacy_payment.complex_legacy_method # Just hiding the problem end end

RIGHT - Either refactor properly or track explicitly

If time-constrained, create beads issue with clear scope

→ Debt wrappers compound into "debt squared". Refactor or track, don't hide.

NEVER disable linters globally to silence debt warnings:

WRONG - Global disable in .rubocop.yml

Metrics/MethodLength: Enabled: false # Hides ALL long method debt

RIGHT - Explicit inline disable with justification

rubocop:disable Metrics/MethodLength -- Legacy payment processor, tracked in PROJ-123

def complex_legacy_method

...

end

rubocop:enable Metrics/MethodLength

→ Global disables hide debt accumulation. Use inline disables with tracking.

NEVER skip team discussion on Critical/High debt:

WRONG - Solo decision on major debt

"I found a god object, I'll refactor it this sprint"

RIGHT - Team alignment first

1. Document finding in debt report
2. Create beads issue with severity
3. Discuss in sprint planning
4. Get consensus on approach

→ Major refactoring affects the whole team. Collaborate before large changes.

NEVER estimate features without considering debt in affected areas:

WRONG - Ignoring debt in estimates

"Add payment retry logic: 2 story points"

RIGHT - Include debt impact

"Add payment retry logic: 5 story points

• 2 points: feature implementation
• 3 points: PaymentService complexity (Flog 127) requires refactoring first"

→ Debt adds hidden cost. Include remediation in feature estimates.

Code Smell Detection Patterns

Long Method (>20 lines)

Detection:

Find methods longer than 20 lines

awk ' /^[[:space:]]*def / { start = NR; name = $2 } /^[[:space:]]end/ && start > 0 { len = NR - start if (len > 20) print FILENAME ":" name " (" len " lines)" start = 0 } ' app/**/.rb

Severity Thresholds:

Lines Severity

20-40 Medium

40-80 High

80 Critical

Large Class (>150 lines)

Detection:

Find classes larger than 150 lines

for file in app/models/.rb app/services/.rb; do lines=$(wc -l < "$file" 2>/dev/null) if [ "$lines" -gt 150 ]; then echo "$file: $lines lines" fi done

Severity Thresholds:

Lines Severity

150-300 Medium

300-500 High

500 Critical

Feature Envy

Method uses another object's data more than its own.

Detection Pattern:

Smell: Method calls another object's methods repeatedly

def calculate_total(order) order.items.sum(&:price) + order.shipping_cost + order.tax_amount - order.discount_amount end

Fix: Move method to Order class

class Order def calculate_total items.sum(&:price) + shipping_cost + tax_amount - discount_amount end end

Data Clump

Same group of parameters passed together repeatedly.

Detection Pattern:

Smell: Repeated parameter group

def create_user(name, email, phone, address) def update_user(name, email, phone, address) def validate_user(name, email, phone, address)

Fix: Extract to value object

class ContactInfo attr_reader :name, :email, :phone, :address end

def create_user(contact_info) def update_user(contact_info)

Complexity Metrics

Flog Score Thresholds

Score Rating Action

< 30 Low No action needed

30-60 Medium Consider refactoring

60-100 High Plan refactoring

100 Critical Immediate refactoring

Running Flog:

Overall complexity score

flog -q -g app/

Top 10 most complex methods

flog -q app/ | head -10

Score for specific file

flog app/services/payment_service.rb

Cyclomatic Complexity

Measures independent execution paths through code.

Complexity Rating Risk

1-5 Low Easy to test

6-10 Medium Moderate risk

11-20 High Difficult to test

20 Critical Very high risk

Severity Scoring Framework

Calculate overall severity using weighted factors:

Severity Score = (Blast × 0.30) + (Fix × 0.20) + (Risk × 0.30) + (Age × 0.10) + (Freq × 0.10)

Factor Weight 1 (Low) 3 (Medium) 5 (High)

Blast Radius 30% Single file Module System-wide

Fix Complexity 20% Trivial Moderate Major refactor

Risk Level 30% Cosmetic Functional Security/Data

Age 10% < 6 months 6mo-2yr

2 years

Frequency 10% Rare path Normal Hot path

Severity Categories:

• Critical: Score >= 4.0 (SLA: 1 sprint)

• High: Score >= 3.0 (SLA: 2 sprints)

• Medium: Score >= 2.0 (SLA: Quarterly)

• Low: Score < 2.0 (Opportunistic)

Quick Reference Tables

Detection Tools

Tool Purpose Command

Flog Complexity scoring flog -q app/

Reek Code smell detection reek app/

Rubocop Style + metrics rubocop --format json

Brakeman Security vulnerabilities brakeman -q

bundler-audit Gem CVEs bundle-audit check

rails_best_practices Rails anti-patterns rails_best_practices

Effort Estimation

Category Typical Effort

Long Method refactor 2-4 hours

Large Class extraction 1-3 days

God Object decomposition 3-5 days

N+1 query fix 1-2 hours

Security vulnerability 2-8 hours

Deprecation update 2-4 hours

Circular dependency fix 2-5 days

Beads Integration

Create debt issue

bd create --type task --priority 1
--title "Tech Debt: [Description]"
--description "[Details]"

Track debt item

bd update PROJ-123 --status in_progress

Close after remediation

bd close PROJ-123 --reason "Refactored in commit abc123"

References

For detailed patterns in each category, see:

• references/code-smells.md

• Long method, large class, feature envy, data clump

• references/complexity-metrics.md

• Flog, cyclomatic, cognitive complexity

• references/deprecation-tracking.md

• Rails, Ruby, gem deprecations

• references/security-debt.md

• Brakeman categories, OWASP patterns

• references/performance-debt.md

• N+1 queries, indexes, memory

• references/testing-debt.md

• Coverage gaps, flaky tests

• references/architecture-debt.md

• God objects, circular deps, layers

Integration with Other Skills

Skill Integration Point

code-quality-gates

Rubocop/Sorbet findings feed into debt report

refactoring-workflow

Debt items become refactoring targets

rails-conventions

Convention violations are architecture debt

codebase-inspection

Inspector discovers debt during analysis