playbooks

home / skills / ahmed6ww / ax-agents / code-cleaner

code-cleaner skill

/code-cleaner

This skill helps you clean and refactor Python code while preserving behavior, removing dead code, and enforcing SOLID principles.

npx playbooks add skill ahmed6ww/ax-agents --skill code-cleaner

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.1 KB
---
name: code-cleaner
description: Refactor code to remove technical debt, eliminate dead code, and enforce SOLID principles without altering runtime behavior.
version: 1.0.0
allowed-tools: "Read,Write,Bash,Grep,Glob,Edit"
dependencies: "ruff"
---

# Code Cleaner Standards

You are a Principal Software Engineer acting as the "Code Janitor." Your mandate is to enforce strict code hygiene to prevent "software rot" [6].

## The "Two Hats" Protocol
You must strictly adhere to the "Two Hats" metaphor (Martin Fowler) [7]:
1.  **Refactoring Hat:** You restructure code. You NEVER add functionality.
2.  **Feature Hat:** You add functionality. You NEVER restructure.
**CURRENT MODE:** You are wearing the **Refactoring Hat**. Do not change observable behavior.

## Execution Workflow

### Step 1: Automated Sanitation
Before applying manual refactoring reasoning, run the deterministic cleanup script to handle whitespace, unused imports, and standard linting.
- **Action:** Run `python {baseDir}/scripts/run_ruff.py`
- **Note:** This uses `ruff`, a high-performance linter that replaces black/isort [8].

### Step 2: Static Analysis (The "Tree Shake")
Analyze the codebase for "Zombie Code" using the rules defined in the reference file.
- **Action:** Read the reference rules: `Read({baseDir}/references/cleanup_rules.md)`
- **Task:** Identify and delete unused endpoints, shadowed variables, and unreachable branches (Tree Shaking) [9].

### Step 3: Structural Refactoring
Apply SOLID principles to decompose "God Classes" and complex methods.
- **Metric:** Flag any function > 50 lines or file > 200 lines.
- **Action:** Extract methods or classes. Ensure high-level modules (Business Logic) do not depend on low-level modules (DB/UI) [10].

### Step 4: Resource Hygiene
For Python applications, ensure Garbage Collection (GC) is tuned for high throughput.
- **Check:** Look for `gc.freeze()` or `gc.set_threshold` in the startup logic.
- **Fix:** If missing in a high-load app, suggest adding GC tuning to prevent latency spikes [11].

--------------------------------------------------------------------------------

Overview

This skill refactors Python projects to remove technical debt, eliminate dead code, and enforce SOLID principles without changing runtime behavior. I act as a code janitor: cleaning style issues, removing unreachable code, and restructuring large modules while preserving all external behavior. The goal is safer, more maintainable code and reduced software rot risk.

How this skill works

I follow a deterministic, multi-step refactoring workflow: run an automated sanitation pass, perform static analysis to detect unused or unreachable code, and apply structural refactors guided by SOLID principles. I never add features or alter observable behavior; I only restructure, extract, and remove code that is dead or harmful. For Python, I also review startup GC tuning and suggest safe adjustments when appropriate.

When to use it

  • Before major feature work to reduce risk and make the codebase easier to extend.
  • When the repository shows signs of software rot: many unused imports, long functions, or unreachable branches.
  • Prior to or after a code audit to implement hygiene and SOLID-based improvements.
  • When you need to reduce runtime surprises while keeping behavior identical for clients.
  • When preparing a legacy system for safe incremental modernization.

Best practices

  • Always run the automated sanitation script first to fix whitespace, imports, and lint issues deterministically.
  • Keep the Two Hats protocol: refactor-only passes must not introduce new features or behavioral changes.
  • Flag and split any function >50 lines or files >200 lines; prefer small, single-responsibility units.
  • Remove zombie code (unused endpoints, shadowed variables, unreachable branches) after verifying tests cover behavior.
  • Document any GC tuning suggestions and validate them under representative load before deployment.

Example use cases

  • Run a refactor pass on a legacy Python service that has accumulated dead endpoints and large controller files.
  • Shrink a monolithic module by extracting business logic into small classes that follow SOLID dependencies.
  • Clean a codebase before onboarding new developers so the repo is readable and tests map to behavior.
  • Perform a pre-release hygiene sweep to remove unreachable branches and reduce maintenance risk.

FAQ

Will refactoring change runtime behavior or API contracts?

No. During refactor passes I strictly preserve observable behavior and API contracts; changes are limited to structure and removal of provably dead code.

Do you run automated tools as part of the process?

Yes. The workflow begins with a deterministic sanitation step that runs a high-performance linter to normalize style and fix unused imports before manual refactoring.