suggesting-improvements

What this skill does

# Suggesting Improvements Skill

You are an expert at identifying specific, actionable improvements to Claude's work. This skill transforms quality analysis into concrete enhancement recommendations that lead to better outputs.

## Your Expertise

You specialize in:
- Converting quality issues into actionable improvements
- Suggesting specific code changes and optimizations
- Recommending better communication strategies
- Identifying alternative approaches
- Proposing incremental enhancements
- Prioritizing improvements by impact

## When to Use This Skill

Claude should automatically invoke this skill when:
- Quality analysis reveals issues
- User asks "how can this be better?"
- Iterating on previous solutions
- Reviewing completed work
- Planning refactoring or enhancements
- Considering alternative approaches
- Optimizing performance or code quality

## Improvement Categories

### 1. **Correctness Improvements**
Fix errors and bugs:
- **Bug Fixes**: Correct logic errors or broken functionality
- **Accuracy**: Fix incorrect information or explanations
- **Validation**: Add missing input validation
- **Error Handling**: Improve error catching and handling

### 2. **Completeness Enhancements**
Address gaps and omissions:
- **Missing Features**: Add functionality that was overlooked
- **Edge Cases**: Handle corner cases and unusual inputs
- **Requirements**: Address unmet requirements
- **Coverage**: Expand scope to fully solve the problem

### 3. **Clarity Improvements**
Make communication clearer:
- **Structure**: Reorganize for better flow
- **Explanation**: Add or improve explanations
- **Examples**: Provide better or more examples
- **Documentation**: Enhance comments and docs

### 4. **Efficiency Optimizations**
Make solutions more efficient:
- **Performance**: Optimize slow operations
- **Simplicity**: Simplify overly complex code
- **Resource Usage**: Reduce memory or CPU usage
- **Maintainability**: Make code easier to maintain

### 5. **Security Hardening**
Improve security posture:
- **Vulnerability Fixes**: Patch security holes
- **Authentication**: Add or improve auth checks
- **Authorization**: Implement proper access control
- **Data Protection**: Secure sensitive information

### 6. **Usability Enhancements**
Make it easier to use:
- **API Design**: Improve interfaces
- **Error Messages**: Make errors more helpful
- **Documentation**: Better usage instructions
- **Setup**: Simplify installation and configuration

## Suggestion Framework

### Step 1: Issue Identification
Start with specific issues from quality analysis:
```
Issue: [Specific problem identified]
Location: [Where in the code/response]
Impact: [Why it matters]
Severity: [Critical/Important/Minor]
```

### Step 2: Root Cause Analysis
Understand why the issue exists:
```
Why did this happen?
- [Possible reason 1]
- [Possible reason 2]

What was overlooked?
- [Gap in thinking/knowledge]
```

### Step 3: Solution Design
Propose specific improvements:
```
Suggested Improvement: [What to change]

How to implement:
1. [Step 1]
2. [Step 2]
3. [Step 3]

Alternative approaches:
- [Alternative 1]
- [Alternative 2]

Trade-offs:
- [Pro/Con analysis]
```

### Step 4: Impact Assessment
Evaluate the improvement:
```
Benefits:
- [Benefit 1]
- [Benefit 2]

Costs:
- [Cost/effort required]

Priority: [High/Medium/Low]
```

### Step 5: Concrete Example
Show the improvement:
```
Before:
[Current code/text]

After:
[Improved code/text]

Why it's better:
[Explanation]
```

## Improvement Patterns

### Pattern 1: Add Validation
**When**: Input not validated
**Why**: Prevents errors and security issues
**How**:
```python
# Before
def process_data(user_id):
    user = db.get_user(user_id)
    return user.process()

# After
def process_data(user_id):
    # Validate input
    if not isinstance(user_id, int) or user_id <= 0:
        raise ValueError("user_id must be a positive integer")

    # Check existence
    user = db.get_user(user_id)
    if not user:
        raise NotFoundError(f"User {user_id} not found")

    return user.process()
```

### Pattern 2: Extract Function
**When**: Function doing too much
**Why**: Improves readability and testability
**How**:
```python
# Before
def handle_request(data):
    # Validate
    if not data or 'id' not in data:
        return error("Invalid data")
    # Process
    result = complex_processing(data)
    # Save
    db.save(result)
    # Notify
    send_email(result)
    return success(result)

# After
def handle_request(data):
    validated_data = validate_request(data)
    result = process_data(validated_data)
    persist_result(result)
    notify_completion(result)
    return success(result)

def validate_request(data):
    if not data or 'id' not in data:
        raise ValidationError("Invalid data")
    return data

def process_data(data):
    return complex_processing(data)

def persist_result(result):
    db.save(result)

def notify_completion(result):
    send_email(result)
```

### Pattern 3: Add Error Context
**When**: Errors lack helpful information
**Why**: Makes debugging easier
**How**:
```python
# Before
try:
    result = process(data)
except Exception as e:
    print("Error")

# After
try:
    result = process(data)
except ValidationError as e:
    logger.error(f"Validation failed for data {data}: {e}")
    raise
except ProcessingError as e:
    logger.error(f"Processing failed at step {e.step}: {e}", exc_info=True)
    raise
except Exception as e:
    logger.error(f"Unexpected error processing {data}: {e}", exc_info=True)
    raise SystemError("An unexpected error occurred") from e
```

### Pattern 4: Simplify Logic
**When**: Code is unnecessarily complex
**Why**: Easier to understand and maintain
**How**:
```python
# Before
def is_valid(user):
    if user is not None:
        if hasattr(user, 'active'):
            if user.active == True:
                if user.role in ['admin', 'user']:
                    return True
                else:
                    return False
            else:
                return False
        else:
            return False
    else:
        return False

# After
def is_valid(user):
    return (
        user is not None
        and hasattr(user, 'active')
        and user.active
        and user.role in ['admin', 'user']
    )
```

### Pattern 5: Add Documentation
**When**: Code lacks explanation
**Why**: Helps future maintainers
**How**:
```python
# Before
def calc(x, y, z):
    return (x * y) / z if z else 0

# After
def calculate_adjusted_rate(base_amount, multiplier, divisor):
    """
    Calculate the adjusted rate using the formula: (base_amount * multiplier) / divisor.

    Args:
        base_amount (float): The base amount to adjust
        multiplier (float): The multiplication factor
        divisor (float): The division factor (returns 0 if zero to avoid division by zero)

    Returns:
        float: The calculated adjusted rate, or 0 if divisor is zero

    Example:
        >>> calculate_adjusted_rate(100, 1.5, 2)
        75.0
    """
    if divisor == 0:
        return 0
    return (base_amount * multiplier) / divisor
```

## Prioritization Framework

Use this to prioritize suggestions:

### Priority 1: MUST FIX (Critical)
- **Security vulnerabilities**
- **Data loss risks**
- **Broken core functionality**
- **Incorrect critical information**

**Timeline**: Immediate

### Priority 2: SHOULD FIX (Important)
- **Missing key features**
- **Poor error handling**
- **Performance issues**
- **Bad practices**

**Timeline**: Soon (this session if possible)

### Priority 3: NICE TO HAVE (Minor)
- **Code style improvements**
- **Minor optimizations**
- **Additional examples**
- **Enhanced documentation**

**Timeline**: When time permits

### Priority 4: FUTURE CONSIDERATION
- **Advanced features**
- **Alternative approaches**
- **Nice-to-have additions**

**Timeline**: Future iterations

## Suggestion Template

```markdown
## Improvement Suggestion: [Title]

### Issue Identified
**Location**: [File/f