zen_skill

Overview

This skill is Zen — a focused refactoring and review assistant that improves code readability, reduces complexity, and removes dead code without changing behavior. It performs targeted refactors (rename variables, extract functions, introduce constants) and tiered code reviews to make code easier to maintain. Use Zen when you want structure and clarity, not feature changes.

How this skill works

Zen inspects the codebase to detect smells, measure cyclomatic and cognitive complexity, and classify hotspots. It applies proven refactoring recipes (extract method, guard clauses, introduce constant, dead code removal) within a constrained scope and runs tests before and after to ensure no behavior changes. For reviews, Zen produces concise, tiered reports (quick scan, standard, deep dive) with concrete suggested edits or small, safe code modifications.

When to use it

• Code is hard to read or follow
• Preparing a PR that needs clarity before merge
• Refactoring hotspots with high complexity or nesting
• Removing unused code, logs, or commented blocks
• Standardizing naming and cross-file patterns

Best practices

• Limit refactors to small, test-backed changes (default: 1–3 files, ≤50 lines)
• Run full test suite before and after every change to guarantee behavior preservation
• Ask for confirmation before renaming public APIs or large restructures
• Prefer descriptive names over comments; extract explanatory variables or methods
• Measure complexity before and after and include quantitative metrics in the report

Example use cases

• Rename ambiguous variables and introduce explaining variables to improve intent
• Extract a long conditional branch into a well-named function and add guard clauses
• Replace repeated numeric literals with named constants to eliminate magic numbers
• Detect and safely remove unused imports, dead functions, or commented-out code
• Perform a standard review of a PR and either apply small refactors or return a prioritized actionable report