refactor

name	refactor
description	Automated code smell detection and remediation. Detects code smells using a hybrid approach (linters + LLM), fixes session-introduced smells immediately, and creates Worklog work items for pre-existing smells with structured REFACTOR comments to prevent duplicates.

Refactor

Overview

The refactor skill provides automated code smell detection and remediation for agent-implemented code changes. It runs after implementation completes (but before the final commit) to identify and address code quality issues.

Key Concepts

• Session boundary: Only files modified in the current session are analyzed (git diff against parent branch)
• Hybrid detection: Combines linter-based mechanical checks with LLM-based design/architectural analysis
• Auto-fix: Auto-fixable linters (ruff, eslint) resolve mechanical issues in-place before detection
• Pre-existing smells: Non-auto-fixable issues become Worklog work items with REFACTOR comments to prevent duplicates

Architecture

refactor/
├── SKILL.md                   # This file
├── __init__.py                # Package init
├── session_boundary.py        # Git diff session boundary detection
├── smell_detection.py         # Hybrid linter + LLM smell detection
├── workitem_creation.py       # Worklog work item creation
├── comment_injection.py       # Structured REFACTOR comment injection
└── scripts/
    ├── __init__.py            # Scripts package init
    └── refactor.py            # Main orchestration script

When To Use

• As a post-implementation quality check in the implement workflow.
• Manually via /refactor <work-item-id> to run code smell analysis on session changes.
• Integrated into CI/CD pipelines for automated code quality gates.

Verification

Refactoring changes must be verified against the full project test suite before completion. Run the suite via the test skill (/skill:test — run → triage → evaluate → loop until green), following the quiet pytest contract, so refactor fixes do not silently break behavior.

Status Management

The refactor script manages work item status automatically via the shared StatusLifecycle context manager when invoked with a work-item-id.

• On entry: Status is set to in_progress
• On success: Original status is restored (restore_on_exit=True — this read-only skill never advances the item to completed, which wl only allows for in_review/done stages)
• On error: Status is restored to its original value

No manual wl update --status commands are needed — the script handles lifecycle transparently. Stage is NOT modified by this skill. The item is never left in in_progress when the script exits.

In --dry-run mode, status management is skipped entirely, since no changes are being made and no work item context is expected.

Invocation

python -m skill.refactor.scripts.refactor [<work-item-id>] [--no-llm] [--no-linter] [--dry-run] [--json] [--parent-branch <branch>] [--config <path>]

• If a <work-item-id> is provided and --dry-run is not set, the script will manage the work item's status using StatusLifecycle.
• If no <work-item-id> is provided or --dry-run is set, the script runs without any work item status interaction.

Usage

Invocation

python -m skill.refactor.scripts.refactor [<work-item-id>] [--no-llm] [--no-linter] [--dry-run] [--json] [--parent-branch <branch>] [--config <path>]

Agent invocation: /refactor <work-item-id>

Output

Structured report with: files analyzed, smells detected, smells fixed, work items created, REFACTOR comments injected.

Configuration

Command-line flags

Flag	Description
--no-llm	Disable LLM-based detection (linter only)
--no-linter	Disable linter detection (LLM only)
--dry-run	Show what would be changed without making changes
--json	Output results in JSON format
--parent-branch <branch>	Override parent branch for diff (default: dev)
--config <path>	Path to custom .refactor.json config file

.refactor.json Configuration

Example config (project root):

{
  "linter": { "enabled": true, "severity_overrides": {} },
  "llm": { "enabled": true, "model": "default", "temperature": 0.1, "max_tokens": 2000 },
  "severity_mapping": { "critical": "high", "high": "high", "medium": "medium", "low": "low" },
  "smell_types": ["unused_import"   
        

Smell Types

Code / Type	Description	Detection	Severity
F401	Unused import	Linter	Critical
F841	Unused variable	Linter	Critical
E302	Missing blank lines	Linter	High
C901	Complex function (mccabe)	Linter	Low
unused_function	Function defined but never called	LLM	Medium
magic_number	Numeric literal without named constant	LLM	Low
god_class	Class with too many responsibilities	LLM	High
feature_envy	Method overly interested in another class	LLM	Medium
shotgun_surgery	Single change requires many file modifications	LLM	Medium
inappropriate_intimacy	Classes that know too much about each other	LLM	Medium

REFACTOR Comments

When a pre-existing smell is detected, a structured REFACTOR comment is injected:

<!-- REFACTOR-SA-0MOCK9999
smell: <type>
severity: <level>
description: <text>
-->

Comment delimiters vary by file type — # for Python, // for JS/TS, <!-- --> for HTML/Markdown.

Error Handling

• Missing git repo: Returns empty session (no files to analyze)
• No linter: Falls back to LLM-only detection
• No LLM client: Falls back to linter-only detection
• File permission errors: Skips file, logs warning
• Binary files: Handled gracefully

Related Skills

• Implement — Integrated refactor step
• Code Review — Complementary code quality skill