Proactive Suggestions Expert

Intelligent Code Improvement Recommendations

Focus: Code Quality, Security, Performance, Best Practices
Approach: Analyze → Suggest → Prioritize

---

Overview

Automatically detect improvement opportunities and provide actionable suggestions.

Suggestion Categories

1. Code Quality: Readability, maintainability
2. Security: Vulnerabilities, best practices
3. Performance: Bottlenecks, optimization opportunities
4. Architecture: Design patterns, structure

---

Suggestion Patterns

1. Code Quality Suggestions

Pattern: Overly Complex Function

# Detected Issue
def process_data(data):
    if len(data) > 0:
        for item in data:
            if item['status'] == 'active':
                if item['type'] == 'user':
                    # 20+ more lines...

# Suggestion
✅ **Simplify Logic**:
- Extract nested loops into separate functions
- Use early returns to reduce nesting
- Current complexity: 15 → Target: <10

# Improved
def process_data(data):
    active_users = filter_active_users(data)
    return [process_user(user) for user in active_users]

2. Security Suggestions

Pattern: Hardcoded Secrets

# Detected Issue
API_KEY = "sk-1234567890abcdef"

# Suggestion
❌ **Security Risk: Hardcoded Secret**
- Move to environment variable
- Use secrets management (e.g., .env, AWS Secrets Manager)
- Add .env to .gitignore

# Fixed
import os
API_KEY = os.getenv("API_KEY")

3. Performance Suggestions

Pattern: N+1 Query

# Detected Issue
users = User.query.all()
for user in users:
    posts = Post.query.filter_by(user_id=user.id).all()

# Suggestion
⚡ **Performance: N+1 Query Detected**
- Use eager loading (joinedload)
- Reduces queries from N+1 to 1

# Optimized
users = User.query.options(joinedload(User.posts)).all()

4. Best Practice Suggestions

Pattern: Missing Type Hints

# Detected Issue
def calculate_total(items):
    return sum(item.price for item in items)

# Suggestion
📝 **Best Practice: Add Type Hints**
- Improves IDE autocomplete
- Catches type errors early
- Self-documenting code

# Improved
from typing import List

def calculate_total(items: List[Item]) -> float:
    return sum(item.price for item in items)

---

Suggestion Priority Levels

Critical (🔴 Fix Immediately)

• Security vulnerabilities
• Data loss risks
• Production bugs

High (🟡 Fix Soon)

• Performance bottlenecks (>2x improvement possible)
• Code smells affecting maintainability
• Missing error handling

Medium (🟢 Consider)

• Code style inconsistencies
• Missing documentation
• Potential refactoring

Low (ℹ️ Optional)

• Minor optimizations
• Cosmetic improvements

---

Suggestion Workflow

1. Analyze: Scan code for patterns
2. Detect: Identify improvement opportunities
3. Prioritize: Rank by impact and effort
4. Suggest: Provide actionable recommendations
5. Track: Monitor adoption rate

---

Example Suggestions

Missing Error Handling

# Current
def fetch_data(url):
    response = requests.get(url)
    return response.json()

# Suggestion
🛡️ **Add Error Handling**
- Network failures not handled
- Invalid JSON not handled

# Improved
def fetch_data(url):
    try:
        response = requests.get(url, timeout=5)
        response.raise_for_status()
        return response.json()
    except requests.Timeout:
        logger.error(f"Timeout fetching {url}")
        raise
    except requests.HTTPError as e:
        logger.error(f"HTTP error: {e}")
        raise

---

Validation Checklist

• Actionable: Suggestions include concrete fixes?
• Prioritized: Critical issues flagged first?
• Justified: Explanation provided for each suggestion?
• Measurable: Impact quantified (e.g., "2x faster")?

---

Related Skills

• moai-essentials-review: Code review
• moai-essentials-refactor: Refactoring patterns
• moai-security-devsecops: Security scanning

---

Last Updated: 2025-11-20