quality-fixer

Quality Fix Applier

⚠️ MANDATORY: Read Project Documentation First

BEFORE applying quality fixes, you MUST read and understand the following project documentation:

Core Project Documentation

1. README.md - Project overview, features, and getting started
2. AI_DOCS/project-context.md - Tech stack, architecture, development workflow
3. AI_DOCS/code-conventions.md - Code style, formatting, best practices
4. AI_DOCS/tdd-workflow.md - TDD process, testing standards, coverage requirements

Session Context (if available)

1. .ai-context/ACTIVE_TASKS.md - Current tasks and priorities
2. .ai-context/CONVENTIONS.md - Project-specific conventions
3. .ai-context/RECENT_DECISIONS.md - Recent architectural decisions
4. .ai-context/LAST_SESSION_SUMMARY.md - Previous session summary

Additional AI Documentation

1. AI_DOCS/ai-tools.md - Session management workflow
2. AI_DOCS/ai-skills.md - Other specialized skills/agents available

Why This Matters

• Tool Configuration: Understand which formatters and linters are configured
• Code Standards: Apply fixes that align with project conventions
• Safety Rules: Know which auto-fixes are safe vs. require manual review
• Integration: Coordinate with other quality tools (Black, Ruff, isort)

After reading these files, proceed with your quality fixing task below.

Overview

Automatically apply safe quality fixes to Python code, resolving formatting issues, linting problems, and formatter conflicts.

When to Use

• After writing code, before running make check
• When make lint or make format reports fixable issues
• To resolve Black vs Ruff formatter conflicts
• Before committing code to ensure quality gates pass
• When you want to apply all safe, automatic fixes

What This Skill Fixes

✅ Formatting Issues

• Black code formatting
• isort import sorting
• Line length adjustments
• Whitespace normalization

✅ Linting Issues (Safe Auto-Fixes)

• Unused imports removal
• Unused variables (when safe)
• F-string conversion
• Simplifiable if statements
• List/dict comprehension improvements

✅ Type Hint Issues (Safe Cases)

• Add -> None to functions without return
• Add obvious type hints (str, int, bool literals)
• Fix Ellipsis in stub signatures

✅ Formatter Conflicts

• Black vs Ruff disagreements
• Message variable extraction for long strings
• Line break adjustments

Usage Examples

Fix All Issues in Project

# Run comprehensive quality fixes
apply quality fixes to the entire project

Actions:

1. Run make format (Black + isort)
2. Run Ruff with --fix flag
3. Check for and resolve formatter conflicts
4. Report what was fixed

Fix Specific File

# Fix a single file
fix quality issues in src/python_modern_template/validators.py

Actions:

1. Format the specific file
2. Apply Ruff fixes to that file
3. Verify no conflicts introduced
4. Show diff of changes

Resolve Formatter Conflicts Only

# Focus on conflicts
resolve Black and Ruff formatter conflicts

Actions:

1. Run both formatters
2. Identify lines where they disagree
3. Apply conflict resolution strategies
4. Verify both are satisfied

Preview Mode (Dry Run)

# See what would be fixed without applying
preview quality fixes for src/

Actions:

1. Run all checks in dry-run mode
2. Show what would be changed
3. Ask for confirmation before applying

Step-by-Step Process

Step 1: Run Formatting

# Apply Black formatting
make format

# This runs:
# - black src/ tests/
# - isort src/ tests/

What gets fixed:

• Code style (spacing, indentation, quotes)
• Import organization and grouping
• Line length compliance (88 characters)

Step 2: Apply Ruff Auto-Fixes

# Run Ruff with auto-fix
uv run ruff check --fix src/ tests/

# Safe fixes include:
# - Remove unused imports
# - Remove unused variables (when safe)
# - F-string conversion
# - Simplify expressions

What gets fixed:

• Import cleanup
• Code simplification
• Modern Python idioms

Step 3: Detect Formatter Conflicts

# Check if Black and Ruff agree
make format && make lint

Common conflicts:

• Long string literals exceeding line length
• Complex expressions needing line breaks
• Comment placement differences

Step 4: Resolve Conflicts

Strategy 1: Extract Message Variables

# Before (conflict - too long)
logger.error("This is a very long error message that exceeds the line length limit")

# After (resolved)
msg = "This is a very long error message that exceeds the line length limit"
logger.error(msg)

Strategy 2: Use Parentheses for Line Breaks

# Before (conflict)
result = some_function(arg1, arg2, arg3, arg4, arg5, arg6)

# After (resolved)
result = some_function(
    arg1, arg2, arg3, arg4, arg5, arg6
)

Strategy 3: Split Long Strings

# Before (conflict)
text = "This is a very long string that should be split across multiple lines for readability"

# After (resolved)
text = (
    "This is a very long string that should be "
    "split across multiple lines for readability"
)

Step 5: Verify Fixes

# Run complete quality check
make check

Must pass:

• ✅ Format (Black + isort)
• ✅ Lint (Ruff + Pylint + mypy)
• ✅ Tests (pytest)
• ✅ Security (Bandit)

Conflict Resolution Strategies

Identifying Conflicts

Run both tools and compare:

# Apply Black
black src/python_modern_template/module.py

# Check Ruff
ruff check src/python_modern_template/module.py

# If Ruff still complains about formatting, there's a conflict

Resolution Decision Tree

1. Long String Literals

→ Extract to variable or split across lines

1. Complex Expressions

→ Add parentheses and line breaks

1. Long Function Calls

→ Break arguments to multiple lines

1. Comment Placement

→ Move comments above the line

1. Type Annotation Complexity

→ Split to multiple lines with proper indentation

Example: Resolving Long String Conflict

Problem:

# Black formats this way:
raise ValueError("The email address provided is not valid because it does not contain the required @ symbol")

# Ruff complains: E501 Line too long (92 > 88)

Solution:

# Extract message variable
error_msg = (
    "The email address provided is not valid because it "
    "does not contain the required @ symbol"
)
raise ValueError(error_msg)

# Both Black and Ruff are satisfied!

What This Skill Does NOT Fix

❌ Complex Logic Issues

• Algorithm problems
• Business logic errors
• Design flaws

❌ Non-Obvious Type Hints

• Complex generic types
• Union types requiring domain knowledge
• Custom type aliases

❌ Docstring Content

• Will format docstrings
• Won't write missing docstrings
• Won't improve docstring quality

❌ Test Failures

• Only fixes code style
• Doesn't fix failing tests
• Doesn't add missing tests

❌ Breaking Changes

• Only applies safe, non-breaking fixes
• Won't remove used variables
• Won't change semantics

Output Format

After applying fixes, provide a report:

## Quality Fixes Applied

**Files Modified:** X
**Total Changes:** X lines

### Formatting Fixes
- ✅ Applied Black formatting to X files
- ✅ Sorted imports with isort in X files
- ✅ Fixed line length issues: X lines

### Linting Fixes
- ✅ Removed X unused imports
- ✅ Converted X strings to f-strings
- ✅ Simplified X expressions
- ✅ Fixed X Ruff issues

### Conflicts Resolved
- ✅ Extracted X message variables
- ✅ Split X long strings
- ✅ Reformatted X function calls

### Quality Check Results

make check

[Show output]

### Files Changed
1. src/python_modern_template/module1.py (+12, -8)
2. src/python_modern_template/module2.py (+5, -3)
3. tests/test_module.py (+3, -2)

### Next Steps
- Review changes with `git diff`
- Run tests to ensure no break