suggesting-improvements

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:

# 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:

# 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:

# 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:

# 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:

# 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

## Improvement Suggestion: [Title]

### Issue Identified
**Location**: [File/function/line or section]
**Current State**: [What exists now]
**Problem**: [What's wrong or missing]
**Impact**: [Why it matters]

### Proposed Improvement
**Change**: [What to do]
**Why**: [Rationale]
**Priority**: [High/Medium/Low]

### Implementation

#### Approach 1 (Recommended)
```[code/text]
[Improved version]

Steps:

1. [Step 1]
2. [Step 2]
3. [Step 3]

Benefits:

• [Benefit 1]
• [Benefit 2]

Trade-offs:

• [Consideration 1]

Approach 2 (Alternative)

[Alternative version]

When to use: [Context where this is better]

Verification

How to test:

• [Test 1]
• [Test 2]

Success criteria:

• [Criterion 1]
• [Criterion 2]

Learning Point

[What pattern or principle this teaches]

## Improvement Categories by Context

### For Code
1. **Refactoring**: Improve structure without changing behavior
2. **Optimization**: Make it faster or more efficient
3. **Security**: Harden against attacks
4. **Testing**: Add or improve tests
5. **Documentation**: Explain better
6. **Error Handling**: Handle failures gracefully
7. **Validation**: Check inputs
8. **Maintainability**: Make it easier to maintain

### For Explanations
1. **Clarity**: Explain more clearly
2. **Structure**: Organize better
3. **Examples**: Add or improve examples
4. **Completeness**: Cover all aspects
5. **Accuracy**: Fix errors
6. **Context**: Provide background
7. **Actionability**: Make it more useful
8. **Brevity**: Remove unnecessary verbosity

### For Solutions
1. **Simplicity**: Use simpler approach
2. **Robustness**: Handle edge cases
3. **Scalability**: Work at larger scale
4. **Flexibility**: Make it more configurable
5. **Performance**: Speed it up
6. **Usability**: Make it easier to use
7. **Completeness**: Add missing pieces
8. **Best Practices**: Follow conventions

## Improvement Checklist

Before suggesting an improvement, verify:

- [ ] **Specific**: Is the suggestion concrete and actionable?
- [ ] **Justified**: Is there a clear reas

---

*Content truncated.*