Imported from superhealth/skills-hub (skills/c0ntr0lledcha0s/suggesting-improvements/SKILL.md). Install upstream with npx skills add superhealth/skills-hub --skill suggesting-improvements. Copyright stays with the author.

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 reason why this is better?
- [ ] **Feasible**: Can it realistically be implemented?
- [ ] **Impactful**: Will it meaningfully improve the output?
- [ ] **Prioritized**: Is the priority level appropriate?
- [ ] **Explained**: Are the steps clear?
- [ ] **Demonstrated**: Is there a before/after example?
- [ ] **Tested**: Is there a way to verify it worked?

## Examples

### Example 1: Security Improvement

**Issue**: SQL injection vulnerability in user login

**Suggestion**:
```markdown
## Improvement: Fix SQL Injection Vulnerability

### Issue Identified
**Location**: auth.py, line 45, login_user function
**Current State**: String concatenation in SQL query
**Problem**: Allows SQL injection attacks
**Impact**: CRITICAL - Attackers can access/modify database

### Proposed Improvement
**Change**: Use parameterized queries
**Why**: Prevents SQL injection by separating SQL from data
**Priority**: CRITICAL - Must fix immediately

### Implementation

#### Before
```python
def login_user(username, password):
    query = f"SELECT * FROM users WHERE username='{username}' AND password='{password}'"
    return db.execute(query)

After

def login_user(username, password):
    query = "SELECT * FROM users WHERE username=? AND password=?"
    return db.execute(query, (username, password))

Steps:

1. Replace f-string with parameterized query (?)
2. Pass values as tuple in second argument
3. Test with malicious input like: ' OR '1'='1

Benefits:

• Prevents SQL injection attacks
• Follows security best practices
• No performance impact

Verification

How to test:

• Try login with: username = ' OR '1'='1, password = anything
• Should fail authentication, not return all users
• Run automated security scanner

Success criteria:

• Malicious SQL inputs don't execute
• Normal authentication still works
• Security scanner shows no SQL injection

Learning Point

Always use parameterized queries or ORMs - never concatenate user input into SQL

### Example 2: Clarity Improvement

**Issue**: Explanation too technical for intended audience

**Suggestion**:
```markdown
## Improvement: Simplify Technical Explanation

### Issue Identified
**Location**: Response explaining async/await
**Current State**: Uses technical jargon without definition
**Problem**: Audience is beginners, explanation assumes knowledge
**Impact**: User likely confused, won't understand concept

### Proposed Improvement
**Change**: Start with simple analogy, progressively add detail
**Why**: Matches user's knowledge level
**Priority**: Important

### Implementation

#### Before

Async/await is syntactic sugar for promises, providing a synchronous-looking syntax for asynchronous operations while maintaining non-blocking I/O through the event loop.

#### After

Think of async/await like ordering food at a restaurant:

Without async/await: You stand at the counter waiting (blocking) until your food is ready. Nobody else can order.

With async/await: You order, get a number (promise), and sit down. The kitchen makes your food (async operation) while others can order. When ready, they call your number (await) and you pick it up.

In code:

// Wait for food without blocking other code
async function getFood() {
    const food = await kitchen.prepare("burger");  // Wait here
    return food;
}

The async keyword says "this function has waiting in it" The await keyword says "wait for this to finish"

**Benefits**:
- Beginner-friendly
- Concrete analogy
- Progressive complexity
- Still technically accurate

### Learning Point
Match explanation complexity to audience level; use analogies before jargon

Your Role

When suggesting improvements:

1. Be specific: No vague "make it better" - show exactly what to change
2. Show examples: Always include before/after code/text
3. Explain why: Justify each suggestion with clear rationale
4. Prioritize: Help Claude focus on what matters most
5. Provide steps: Make implementation easy to follow
6. Consider alternatives: Offer multiple approaches when relevant
7. Teach patterns: Help Claude learn reusable improvement strategies

Important Reminders

• Actionable over theoretical: Suggestions must be implementable
• Specific over general: "Add error handling in line 45" not "needs better errors"
• Practical over perfect: Good enough often beats perfect
• Incremental over radical: Small improvements compound
• Tested over assumed: Verify improvements actually help
• Learned over forgotten: Extract patterns for future use

Your suggestions create the path to continuously better outputs.