Python Branch Cleanup Skill
This skill reviews, refactors, and documents code changes in your current branch for Python repositories. It focuses on readability, correctness, performance, and consistency with a hard-cut, deletion-first policy.
Skill Overview
This skill analyzes all changes introduced in your branch and performs the following actions:
- Analyze Branch Changes
- Review uncommitted changes and outgoing commits
- Refactor for Readability
- Improve clarity, naming, structure, and modern Python usage
- Enhance Performance
- Identify safe, conservative optimization opportunities
- Add Documentation
- Apply Google-format docstrings
- Ensure Pattern Consistency
- Match the repository's existing module, API, and test patterns
- Validate Examples and Call Sites
- Keep touched code aligned with nearby examples, fixtures, and usage sites
Default Policy
- Prefer a hard cut: keep one canonical implementation and remove fallback, compatibility, adapter, coercion, alias, and dual-shape code unless a real external boundary exists.
- Bias toward deletion: remove obsolete helpers, dead branches, stale comments, and tests that only cover abandoned shapes.
- Keep the end state small and clean: choose intention-revealing names, small single-purpose functions, and code that makes comments unnecessary.
- Validate only the current canonical contract for the branch being changed.
Usage
Invoke the skill using any of the following commands:
- "Clean up my branch code"
- "Refactor the changes in my branch"
- "Review and improve my branch code"
/cleanup-py
What This Skill Does
1. Analyze Branch Changes
The skill retrieves all uncommitted changes and outgoing commits to understand:
- New files added
- Modified files
- Code additions and deletions
- Overall scope and intent of changes
- Contract or API surface changes
- Missing or stale tests
- Generated, cached, or derived files that should not be edited directly
2. Code Refactoring
Readability Improvements
- Replace tuples with named classes or dataclasses
- Improve variable, method, and class naming
- Extract complex logic into well-named helper methods
- Add missing type hints
- Simplify nested or complex conditionals
- Replace deprecated methods and features when the branch owns that work
- Normalize formatting to match the repository's style
Performance Enhancements
- Identify inefficient loops or repeated work
- Suggest appropriate data structures
- Optimize async workflows and I/O
- Remove redundant operations
- Prefer the simplest safe optimization that measurably reduces work
Performance changes are conservative and non-breaking.
3. Documentation
Documentation follows Google-style docstrings.
Class Documentation
class ExampleService:
"""Brief one-line description.
Detailed explanation of the class purpose, responsibilities,
and important behaviors.
Supported features:
- Feature 1
- Feature 2
- Feature 3
"""
Method Documentation
def process_data(self, data: str, options: Optional[dict] = None) -> bool:
"""Process incoming data with optional configuration.
Args:
data: The input data to process.
options: Optional configuration dictionary.
Returns:
True if processing succeeded, False otherwise.
Raises:
ValueError: If data is empty or invalid.
"""
Dataclass Parameters
@dataclass
class InputParams:
"""Configuration parameters for the feature.
Parameters:
timeout: Request timeout in seconds.
retry_count: Number of retry attempts.
enable_logging: Whether to enable debug logging.
"""
timeout: float | None = None
retry_count: int = 3
enable_logging: bool = False
4. Pattern Consistency Checks
Modules and APIs
- Correct inheritance and base-class usage
- Consistent constructor signatures
- Stable public method behavior
- Logging, error handling, and return-value conventions
- Alignment with adjacent modules and existing tests
- Current-shape validation only; do not preserve legacy shapes unless a real external boundary requires it.
5. Specific Implementation Patterns
Service or Worker Implementation
class ExampleWorker:
"""Process and transform branch data for a specific workflow."""
def __init__(self, *, api_key: str | None = None, **kwargs):
self._api_key = api_key or os.getenv("SERVICE_API_KEY")
async def run(self, text: str) -> str:
# ... processing ...
return text.strip()
Repository-Aware Flow
def build_input(data: str) -> str:
"""Normalize input before downstream processing.
Args:
data: Raw input string.
Returns:
Normalized input string.
"""
return data.strip()
Hard-Cut Example
When a branch introduces a new canonical shape, update producers, consumers, fixtures, and tests to use only that shape and delete the old path instead of shimming between both.
Execution Flow
- Fetch uncommitted and outgoing changes
- Categorize files by concern
- Analyze each file:
- Readability
- Performance
- Documentation
- Pattern consistency
- Generate actionable recommendations
- Apply the repository's standards and validation path
Examples
Before: Tuple Usage
def get_audio_info(self) -> Tuple[int, int]:
return (48000, 1)
After: Named Class
class AudioInfo:
"""Audio configuration information.
Parameters:
sample_rate: Sample rate in Hz.
num_channels: Number of audio channels.
"""
sample_rate: int
num_channels: int
def get_audio_info(self) -> AudioInfo:
return AudioInfo(sample_rate=48000, num_channels=1)
Before: Missing Documentation
class NewProcessor:
def __init__(self, api_key: str, mode: str):
self._api_key = api_key
self._mode = mode
After: Fully Documented
class NewProcessor:
"""Text-processing utility using a provider-specific API.
Supported features:
- Input normalization
- Streaming transformations
- Provider customization
- Timing metrics
"""
def __init__(self, *, api_key: str, mode: str):
"""Initialize the service.
Args:
api_key: API key for authentication.
mode: Processing mode to use.
"""
self._api_key = api_key
self._mode = mode
Notes
- Hard-cut the branch to the canonical shape unless a real persisted, on-disk, wire, or public contract prevents it.
- Conservative performance changes only when they are simple, safe, and measurably useful.
- Google-style docstrings, intention-revealing names, and small functions.
- Prefer the repository's canonical formatter, linter, type checker, and tests when available.