clean-code

name	clean-code
version	2.1.0
category	workspace
description	Clean code enforcement for workspace-hub Python repos: file/function size limits, God Object detection, naming rules, dead code removal, and refactor decision guidance. Consult before writing new modules or accepting large files.
type	reference
invocation	/clean-code
applies-to	["Codex","codex","gemini"]
capabilities	[]
requires	[]
updated	"2026-02-25T00:00:00.000Z"
changelog	v2.1.0 — Module Migration Shim Protocol (WRK-602): API compat check, diverged-API handling, patch.object scope for shim modules; v2.0.0 — God Object splits, horizontal-split, parallel team
tags	[]

Clean Code

Sub-Skills

• Hard Limits (Zero-Tolerance)
• Quick Scan Commands
• File Size Decision Tree
• Pattern 1: Responsibility Split (most common) (+5)
• Naming Rules (Enforcement)
• Dead Code Identification and Removal
• God Object Detection
• Top P1 Candidates (2026-02-25 audit)
• Pre-commit Integration
• Git Plumbing for Repos with Large Pack Files (+1)
• Step 1: API Compatibility Check (MANDATORY before writing shims) (+2)
• See Also

Iron Law

No file shall exceed the hard limit, and no function shall exceed 50 lines — no exceptions, no deferrals, no "I'll refactor later."

Rationalization Defense

Excuse	Reality
"It's only slightly over the limit"	Limits exist at exact thresholds for a reason — 301 lines is a violation, not a rounding error. Split now.
"Splitting this file would be premature"	The limit exists precisely because developers always say this. The file is already too large; splitting is overdue, not premature.
"I'll refactor after I finish the feature"	Post-feature refactors have a near-zero completion rate. The limit is enforced at write time, not review time.
"This function is complex — it needs to be long"	Complex functions need to be decomposed, not excused. Length is a symptom of missing abstractions.
"The tests pass so the structure is fine"	Tests validate behavior, not maintainability. Passing tests do not exempt code from structural rules.

Red Flags

These phrases signal you are about to violate the Iron Law:

• "just a few lines over"
• "I'll clean this up in a follow-up"
• "splitting would add unnecessary complexity"