From shipyard
Simplifies complex/AI-generated code by removing duplication, dead code, over-engineering, and bloat patterns like verbose error handling. Use after features, on long functions (>40 lines), deep nesting (>3), or repeated patterns.
npx claudepluginhub lgbarn/shipyard --plugin shipyardThis skill uses the workspace's default tool permissions.
<!-- TOKEN BUDGET: 400 lines / ~1200 tokens -->
Simplifies code by removing dead code, extracting duplicates (3+ repeats), and reducing nesting (>3 levels). Runs tests before/after to preserve behavior. Ideal wrap-up refactor.
Simplifies code for clarity while preserving exact behavior. Use for refactoring complex but functional code, code reviews, reducing unnecessary complexity, and improving readability/maintainability.
Analyzes existing code for complexity sources like nesting and duplication, then proposes simplifications via extraction, flattening, decoupling, and removal. Use for refactoring, readability improvements, cleanup, and technical debt reduction.
Share bugs, ideas, or general feedback.
The simplifier agent references this skill for systematic cross-task analysis.
AI-generated code accumulates complexity. Each task is implemented in isolation by a fresh agent that can't see the full picture. After multiple tasks, duplication creeps in, abstractions multiply, and dead code lingers.
Core principle: The simplest code that works correctly is the best code. Complexity is a cost, not a feature.
This skill applies after implementation, not during. Don't prematurely optimize -- but don't ship bloat either.
When reviewing code for simplification:
Exact duplicates: Identical code blocks in different files or functions.
# RED FLAG: Same logic in two places
def validate_user_email(email):
if not email or "@" not in email:
raise ValueError("Invalid email")
def validate_contact_email(email):
if not email or "@" not in email:
raise ValueError("Invalid email")
Near duplicates: Same structure, different details.
# RED FLAG: Parallel structure, only names differ
def create_user(data):
validate(data)
user = User(**data)
db.add(user)
db.commit()
return user
def create_project(data):
validate(data)
project = Project(**data)
db.add(project)
db.commit()
return project
Parallel hierarchies: When adding a new type requires changes in multiple places.
Copy-paste config: Same configuration blocks repeated in Docker, Terraform, or CI files.
Extract method: When a function does too many things.
# BEFORE: One function doing everything
def process_order(order):
# validate (10 lines)
# calculate totals (15 lines)
# apply discounts (12 lines)
# save to database (8 lines)
# send notification (6 lines)
# AFTER: Clear responsibilities
def process_order(order):
validate_order(order)
totals = calculate_totals(order)
totals = apply_discounts(totals, order.customer)
save_order(order, totals)
notify_order_placed(order)
Early returns / guard clauses: Eliminate deep nesting.
# BEFORE: Nested conditionals
def get_discount(user):
if user:
if user.is_premium:
if user.years > 5:
return 0.20
else:
return 0.10
else:
return 0.0
else:
return 0.0
# AFTER: Guard clauses
def get_discount(user):
if not user or not user.is_premium:
return 0.0
if user.years > 5:
return 0.20
return 0.10
Replace conditionals with polymorphism: When type-checking drives behavior.
Simplify boolean expressions: Collapse nested boolean logic.
| Metric | Acceptable | Review | Refactor |
|---|---|---|---|
| Function length | < 20 lines | 20-40 lines | > 40 lines |
| Nesting depth | <= 2 levels | 3 levels | > 3 levels |
| Parameters | <= 3 | 4-5 | > 5 |
| Cyclomatic complexity | <= 5 | 6-10 | > 10 |
# OVER-ENGINEERED: Abstract factory for one implementation
class NotificationFactory:
@staticmethod
def create(type):
if type == "email":
return EmailNotifier()
raise ValueError(f"Unknown: {type}")
# SIMPLE: Just use the thing directly
notifier = EmailNotifier()
Rule: If there's only one implementation, don't create an abstraction. Add it when the second implementation arrives.
# OVER-ENGINEERED: Service wrapping a service
class UserService:
def get_user(self, id):
return self.repository.get_user(id) # Just passes through
# SIMPLE: Use the repository directly where needed
user = repository.get_user(id)
# OVER-ENGINEERED
MAX_RETRIES = config.get("max_retries", 3)
# SIMPLE (if this is the only place retries happen)
MAX_RETRIES = 3
Rule: Make it configurable when a second consumer needs a different value, not before.
AI code generators commonly produce these patterns. Watch for them:
# AI BLOAT: Every function has identical error handling
def get_user(id):
try:
user = db.query(User).get(id)
if user is None:
raise ValueError(f"User {id} not found")
return user
except ValueError:
raise
except Exception as e:
logger.error(f"Error getting user: {e}")
raise RuntimeError(f"Failed to get user {id}") from e
# SIMPLER: Let exceptions propagate naturally
def get_user(id):
user = db.query(User).get(id)
if user is None:
raise ValueError(f"User {id} not found")
return user
# AI BLOAT: Checking types that can't be wrong
def process(items: list[str]) -> None:
if not isinstance(items, list):
raise TypeError("Expected list")
for item in items:
if not isinstance(item, str):
raise TypeError("Expected str")
# actual logic...
# SIMPLER: Trust the type system
def process(items: list[str]) -> None:
for item in items:
# actual logic...
# AI BLOAT: Null checks where nulls can't happen
user = get_authenticated_user() # Already validated by middleware
if user is not None and user.id is not None: # Impossible to be None
process(user)
# SIMPLER: Trust your system boundaries
user = get_authenticated_user()
process(user)
# AI BLOAT: Wrapping standard library
def read_json_file(path):
with open(path) as f:
return json.load(f)
# Used exactly once -- just inline it
with open(config_path) as f:
config = json.load(f)
# AI BLOAT: Excessive logging in every function
my_function() {
log_info "Entering my_function with args: $*"
log_debug "Checking if file exists: $1"
if [ -f "$1" ]; then
log_info "File found: $1"
cat "$1"
log_info "Exiting my_function successfully"
else
log_error "File not found: $1"
return 1
fi
}
# SIMPLER: Let set -e and meaningful exit codes do the work
my_function() {
cat "$1"
}
# AI BLOAT: Wrapping simple commands in functions used once
get_current_branch() { git rev-parse --abbrev-ref HEAD; }
get_repo_root() { git rev-parse --show-toplevel; }
# SIMPLER: Inline when used once
branch=$(git rev-parse --abbrev-ref HEAD)
# AI BLOAT: Redundant existence checks
if [ -n "${MY_VAR:-}" ]; then
if [ "${MY_VAR}" != "" ]; then # Redundant -- -n already checks this
process "$MY_VAR"
fi
fi
# SIMPLER: One check is enough
if [ -n "${MY_VAR:-}" ]; then
process "$MY_VAR"
fi
Finding: Three near-identical validate_request_body() functions in routes/users.py, routes/projects.py, and routes/teams.py.
Before (in each file):
def validate_request_body(body, required_fields):
if not body:
raise HTTPError(400, "Request body required")
for field in required_fields:
if field not in body:
raise HTTPError(400, f"Missing field: {field}")
After (extracted to shared module):
# validators/request.py
def validate_request_body(body, required_fields):
if not body:
raise HTTPError(400, "Request body required")
for field in required_fields:
if field not in body:
raise HTTPError(400, f"Missing field: {field}")
# Each route file now imports:
from validators.request import validate_request_body
Priority: High -- 3 exact duplicates, Rule of Three applies.
| Excuse | Reality |
|---|---|
| "We might need it later" | YAGNI. Add it when you need it. |
| "It's more extensible" | Extensibility without use cases is waste. |
| "The abstraction makes it cleaner" | One caller = inline is cleaner. |
| "Deleting code feels risky" | Git remembers. Dead code is maintenance cost. |
| "It's just a few extra lines" | Lines compound. 10 files x 5 extra lines = 50 lines of noise. |
| "The AI generated it, it must be right" | AI optimizes for completeness, not simplicity. |
| "Refactoring might break things" | Tests exist. If they don't, add them first. |
Referenced by:
Pairs with: