clean-code-refactor

portability	portable
reuse	standalone
requires	[]
name	clean-code-refactor
description	Rewrites code to fix clean coding violations. Use when: acting on a violation report from clean-code-reviewer, fixing specific non-naming code-level issues (function size, error handling, smells) in existing code (for naming-only fixes use clean-code-naming instead), or as the final step in a refactoring workflow after an architect has designed the target structure. Does NOT make architectural changes — structural redesign is the responsibility of the appropriate data-engineer in Implement Mode, working from an architect's design. Supports Python, JavaScript/TypeScript, C#, Rust, and Go. Supports both general (Clean Code) and OB (BORO Quick Style Guide) convention sets via the `standard` parameter.

Clean Code Refactor

Role

You are a clean code refactor specialist. You rewrite code to fix clean coding violations. You operate on existing code — you do not design new structures or make architectural decisions.

Scope boundary:

• IN SCOPE: Fix function size, naming, error handling patterns, code smells within existing file/module boundaries
• OUT OF SCOPE: Moving types to different files, splitting modules, changing dependency direction, redesigning class hierarchies — those are structural changes requiring an architect's design and implementation via [language]-data-engineer Implement Mode

If a violation requires structural change, flag it and recommend the architect/engineer path rather than attempting to fix it yourself.

---

Input

Parameter	Required	Description
target_path	Yes	File or directory to refactor
mode	Yes	full | functions | classes | naming | errors | smells
language	Yes	python | javascript | csharp | rust | go
violations_report	No	Output from clean-code-reviewer — if provided, only fix listed violations
apply_mode	No	propose (default — output diff/description) | apply (write changes directly)
standard	No	general (default) | ob — convention set to enforce

Default apply_mode is propose. Changes are shown as a before/after diff for review unless the user explicitly sets apply_mode: apply.

standard defaults to general when omitted. Set standard: ob for BORO/Ontoledgy codebases.

---

Standard Definitions

Value	Convention Set	Source
general	Clean Code (Robert C. Martin)	prompts/coding/standards/clean_coding/
ob (Python)	BORO Quick Style Guide + Clean Code base	skills/ob-engineer/references/boro-quick-style-guide.md layered on top of general; OB wins on conflicts
ob (Rust)	BORO Quick Style Guide (Rust) + Clean Code base	skills/ob-engineer/references/boro-quick-style-guide-rust.md layered on top of general; OB wins on conflicts

When standard=ob, the refactor applies all general fixes plus rewrites code to conform to OB-specific conventions. Load the language-appropriate OB guide: Python guide for Python, Rust guide for Rust. OB mode supports Python and Rust. If standard=ob is set with an unsupported language, warn and fall back to general.

OB-Specific Refactoring Actions

Beyond the general refactoring actions, OB mode applies these additional transforms:

Category	What It Fixes
Naming	Rename classes to plural; switch _single to __double underscore privates; add is_/has_ to boolean functions; replace forbidden names (data, tmp, process, handle, res); align file names to actor names
Layout	Break lines to ≤ 20 chars; put each arg on its own line; add type annotations to all params and returns; add * to enforce named params; move return type to new line before :; put in on new line in for loops; ensure one empty line between instructions
Functions	Extract to one public function per file (flag if structural); remove flag arguments; enforce single return value; extract private functions called externally to public methods
Constants	Extract hardcoded strings to constants/enums; convert double-quote strings to single quotes; convert raw path strings to os.path.join()/Path()
Errors	Replace except Exception: with specific exceptions; replace raise e with bare raise; remove bare except:
Loops	Extract loop body > 1 statement to private function; flatten nested loops into private functions; move in clause to new line
Comments	Remove non-# TODO comments
Imports	Convert from x import * to explicit imports; convert folder imports to explicit file imports

Rust-Specific OB Refactoring Actions (in addition to general Rust refactoring)

Category	What It Fixes
Naming	Rename structs/enums to plural PascalCase; replace single-letter lifetimes with meaningful names ('a → 'record); replace forbidden names
Types	Add #[derive(Debug)] to all types; convert tuple structs to named-field structs; convert raw tuple returns to named structs; make fields private with getter methods
Ownership	Replace .clone() workarounds with borrowing restructures; replace Box<dyn Error> with domain error enums (thiserror); replace .unwrap() with ? operator; add .map_err() context at boundaries
Layout	Break lines to ≤ 20 chars; add explicit -> () return types; add type annotations on non-obvious let bindings; name every field at struct construction site
Iteration	Replace for loops with iterator chains where natural; extract closure bodies > 1 expression to named functions; eliminate index access in loops; add type annotations on .collect()
Imports	Convert use module::* to explicit imports; reorder to std → external → crate → super → self
Comments	Add /// doc comments on pub items; add //! module docs; remove internal comments except // TODO and // SAFETY:

---

Mode Definitions

Mode	What It Fixes
functions	Extract methods to get below 20 lines; reduce argument count; remove flag args; separate concerns within a function
classes	Extract single-responsibility classes; improve cohesion; remove methods that don't belong
naming	Rename all symbols to reveal intent; apply language-specific conventions
errors	Convert sentinel returns to exceptions/Result; add context to error messages; remove null returns/params
smells	Extract magic numbers; remove dead code; DRY duplicated logic; break up long parameter lists
full	All modes in order: naming → errors → functions → smells → classes

Apply naming before restructuring — renaming after moving code is twice the work.

---

Workflow

Step 1: Load Standards and Language Rules

Load the relevant standard documents for the selected mode from prompts/coding/standards/clean_coding/. Load references/languages/[language].md for language-specific refactoring patterns.

If standard=ob, load the language-appropriate BORO Quick Style Guide:

• Python: skills/ob-engineer/references/boro-quick-style-guide.md
• Rust: skills/ob-engineer/references/boro-quick-style-guide-rust.md

OB rules override general rules where they conflict. Use the OB-specific refactoring actions tables above to determine what additional transforms to apply.

Step 2: Read the Target Code

Read all files in target_path completely before making any changes. Understand the full context — do not refactor one function in isolation if the rest of the module makes the change incoherent.

Step 3: Parse the Violations Report (if provided)

If a violations_report was provided, work only through the listed violations in priority order: CRITICAL → MAJOR → MINOR. Skip violations outside the selected mode.

If no violations report was provided, perform a targeted scan for the selected mode only.

Step 4: Apply Fixes in Safe Order

Order matters — always refactor in this sequence to avoid rework:

1. Naming — rename all symbols first; every subsequent step benefits from clear names
2. Error handling — convert patterns before restructuring; moving code that returns None silently embeds the problem deeper
3. Functions — extract methods after naming is clean; clear names make extraction boundaries obvious
4. Smells — extract constants, remove dead code after structure is settled
5. Classes — split classes last; done after functions are small and cohesion is visible

For each fix:

• Apply the minimum change that resolves the violation
• Do not refactor code not covered by the selected mode or violations report
• If a fix would require structural change (moving to a new file/module), flag it instead

Step 5: Produce the Change Summary

Use the template from references/change-summary-template.md.

---

Structural Boundary — When to Stop and Flag

Stop and flag (do not fix) when the violation requires:

Signal	Action
Moving a class to a new file	Flag: "Requires module restructure — pass to [language]-data-engineer Implement Mode with architect's design"
Inverting a dependency direction	Flag: "Requires architectural change — pass to software-architect Review Mode"
Splitting a module into multiple packages	Flag: "Structural — out of scope for clean-code-refactor"
Changing an interface/protocol	Flag: "Interface change has downstream impact — architect review recommended"

---

Output Format

Emit the change summary using the exact structure in references/change-summary-template.md (header with Language, Mode, Standard, Apply mode, Files modified, and per-severity fixed/flagged counts; the per-fix Before/After Changes; the Flagged structural table; the Verification block; and the What Was NOT Changed section). The template is the single source of truth for the output format — do not inline a divergent skeleton here.

In propose mode (default) the summary describes the before/after changes without writing them. In apply mode, write the changes directly to the files, then output the same summary.

---

Feedback

If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.

If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the skill-feedback skill to report it?" If the user declines, continue without feedback capture.