Roo slash command for over-engineer code assessment

over-engineer-check.md

description
Analyze codebase for over-engineering patterns and unnecessary complexity

Over-Engineering Check

You are tasked with analyzing a codebase to identify signs of over-engineering, unnecessary abstractions, and architectural complexity that doesn't add business value.

Instructions

1. Analyze the Project Structure:

   • Count total files and directory depth
   • Identify abstract classes and their implementations
   • Map inheritance hierarchies
   • Detect wrapper patterns around external APIs
   • Calculate test-to-code ratios

2. Identify Over-Engineering Patterns:

   • Premature Abstraction: Abstract classes with ≤2 implementations
   • File Explosion: Multiple files for single logical units
   • Deep Hierarchies: Inheritance chains >2 levels
   • Wrapper Mania: API wrappers without added value
   • Copy-Paste Inheritance: Nearly identical classes

3. Calculate Metrics:

   • Lines of code (production vs test)
   • Test-to-code ratio
   • Files per thousand lines of code
   • Average file size
   • Directory nesting depth
   • Abstraction-to-implementation ratio

4. Severity Assessment:

   • 🟢 Healthy (0-30): Clean, maintainable code
   • 🟡 Warning (31-60): Some unnecessary complexity
   • 🔴 Critical (61-100): Severe over-engineering

Execution Steps

1. First, check the target directory structure using list_files
2. Count and categorize files by type and purpose
3. Analyze inheritance patterns and class relationships with list_code_definition_names
4. Search for abstract base classes and count implementations
5. Calculate code metrics and duplication
6. Generate severity score and recommendations

Analysis Output Format

Present findings in this structure:

Over-Engineering Analysis: [directory_path]

Severity: [🟢|🟡|🔴] [HEALTHY|WARNING|CRITICAL] (Score: X/100)

Metrics Summary

• Production Code: X lines across Y files
• Test Code: Z lines across W files
• Test-to-Code Ratio: X:1
• Average File Size: X lines
• Max Directory Depth: X levels

Issues Found

1. [Pattern Name] (Impact: [High|Medium|Low])

• Description of the pattern
• Specific examples from codebase
• Files affected: List key files
• Recommendation: Actionable fix

Potential Savings

• Lines of Code: ~X lines (Y% reduction possible)
• File Count: Current → Suggested
• Maintenance Time: Estimated hours/year saved

Refactoring Priority

1. [Highest priority issue]
2. [Second priority issue]
3. [Third priority issue]

Red Flag Patterns

Premature Abstraction

Found: BaseDocumentParser with only PDFParser, DocxParser implementations Issue: All parsers 95% identical, just calling same API Fix: Single configurable parser class

File Explosion

Found: 6+ files for single node implementation
├── node.py
├── params.py
├── schemas.py
├── ports/input.py
├── ports/output.py
└── __init__.py

Issue: Unnecessary file separation Fix: Consolidate into 1-2 files

Issue: Unnecessary file separation Fix: Consolidate into 1-2 files

Wrapper Without Value

Found: ServiceWrapper → ExternalAPI Issue: Just passes through calls Fix: Use ExternalAPI directly

Best Practices Reference

✅ DO

• Start simple, iterate when needed
• Use composition over inheritance
• Keep related code together
• Write for current requirements
• Prefer configuration over new classes

❌ DON'T

• Create abstractions for single use
• Split into many tiny files
• Build for hypothetical futures
• Wrap APIs without adding value
• Test implementation details

Example Cases

Case 1: Document Parser Refactoring

Before: 1,842 lines across 18 files (5 parser classes) After: 198 lines in 1 file Savings: 93.7% code reduction

Case 2: Node System Simplification

Before: 70+ files, 15+ node classes After: 3-4 files with configurable nodes Savings: 90% file reduction

Output Guidelines

1. Always start with severity assessment
2. Provide concrete examples from the analyzed code
3. Include specific file paths and line counts
4. Offer actionable recommendations
5. Estimate potential savings in concrete terms
6. Prioritize refactoring suggestions by impact

Remember: The goal is to identify complexity that doesn't serve the business need. Every abstraction should earn its keep by providing clear value.