style-audit

What this skill does

# Style Audit

This skill transforms functionally correct code into production-grade code through systematic style improvement. While functionality audits verify that code works, style audits ensure that code is maintainable, readable, secure, performant, and aligned with team standards. The skill applies CI/CD quality guidelines to identify style violations, then rewrites code to eliminate issues while preserving functionality.

## When to Use This Skill

Use the style-audit skill after functionality validation confirms code works correctly, before code reviews to catch style issues proactively, when preparing code for team collaboration or handoff, or when inheriting code that works but violates team standards. The skill is essential for maintaining codebases at scale where consistency and maintainability matter more than individual cleverness.

## The Importance of Code Style

Code style is not superficial formatting but fundamental to software maintainability, team effectiveness, and long-term project success.

**Readability and Comprehension**: Code is read far more often than it is written. Every team member who touches the code, every code reviewer who evaluates it, and every future maintainer who debugs it must understand what the code does. Clear, consistent style dramatically reduces the cognitive load of reading code. Developers spend less time deciphering intent and more time implementing improvements or fixes.

Poor style creates confusion that wastes time and introduces bugs. When variable names are cryptic, when formatting is inconsistent, when complex logic lacks decomposition, developers make mistakes because they misunderstand what the code does. Clear style prevents these comprehension failures.

**Maintainability and Evolution**: Software evolves through its lifetime with bug fixes, feature additions, and refactoring. Maintainable code makes evolution straightforward while unmaintainable code turns small changes into large projects. Style choices like proper decomposition into functions, clear separation of concerns, and consistent patterns enable evolution by making it obvious where to add new behavior without breaking existing functionality.

Technical debt accumulates when code is hard to maintain. Style audits prevent technical debt by ensuring code starts in a maintainable state rather than requiring expensive future cleanup.

**Bug Prevention Through Clarity**: Many bugs stem from confusion or misunderstanding. When code structure is clear, when edge cases are explicitly handled, when error conditions are managed properly, bugs become less likely because developers can see what the code does and identify problems visually. Style that promotes clarity also promotes correctness.

Defensive programming practices encoded in style guidelines like input validation, null checking, and explicit error handling prevent entire classes of bugs. Style audits that enforce these practices systematically reduce bug rates.

**Team Collaboration**: Consistent style across a codebase allows team members to move fluidly between different parts of the system. When every file follows the same conventions, developers do not need to mentally shift gears when working in different areas. The cognitive overhead of context switching decreases, and the team becomes more effective overall.

Style consistency also facilitates code review by establishing shared expectations. Reviewers can focus on logic and correctness rather than debating formatting choices. Teams that invest in style consistency experience faster, more effective code reviews.

## Style Audit Methodology

The style audit follows a systematic process to identify style issues and improve code quality.

### Phase 1: Automated Linting

Begin by running automated linting tools appropriate to the programming language. For Python, use pylint, flake8, and mypy for type checking. For JavaScript, use ESLint and Prettier. For other languages, use their standard linters. Automated tools catch common style violations efficiently and consistently.

Collect all linting errors and warnings with their locations, descriptions, and severity levels. Categorize issues by type such as formatting violations, naming convention violations, unused code, missing documentation, potential bugs caught by static analysis, and complexity warnings. This categorization helps prioritize remediation efforts.

Configure linters to match team standards rather than using default configurations. Custom configurations encode team preferences and project requirements, ensuring linting results align with actual quality goals rather than generic recommendations.

### Phase 2: Manual Style Review

Supplement automated linting with manual review for issues that tools cannot detect. Examine code for proper decomposition where functions are appropriately sized and single-purpose, effective naming where identifiers clearly communicate purpose, logical organization where related functionality is grouped coherently, appropriate abstraction where common patterns are extracted, and reasonable complexity where intricate logic includes explanatory comments.

Manual review catches issues that require human judgment such as whether a function is doing too much, whether abstractions make sense, or whether the code will be understandable to future maintainers. Tools flag syntactic issues while humans evaluate semantic quality.

### Phase 3: Security and Performance Review

Review code for security vulnerabilities including input validation to prevent injection attacks, proper authentication and authorization, secure handling of sensitive data, protection against common attack vectors, and safe use of cryptography. Security issues are style issues because secure coding should be the standard style.

Evaluate performance characteristics including algorithmic efficiency to avoid unnecessarily slow operations, memory usage to prevent leaks or bloat, resource cleanup to properly close files and connections, lazy loading where appropriate, and caching strategies for expensive operations. Performance problems often stem from stylistic choices about how to structure code.

### Phase 4: Documentation Review

Assess code documentation including module and file-level documentation explaining purpose, function and method documentation describing parameters and behavior, inline comments explaining non-obvious logic, README files and usage guides for public interfaces, and API documentation for libraries or services. Undocumented code is poorly styled code because it places unnecessary burden on future readers.

Documentation should explain why decisions were made, not just what the code does. The code itself shows what it does. Documentation adds value by explaining intent, rationale, and context that is not apparent from code alone.

### Phase 5: Consistency Analysis

Check for consistency across the codebase including naming convention adherence, formatting style uniformity, error handling patterns, code organization structures, and dependency management approaches. Inconsistency increases cognitive load because developers must constantly adapt to different patterns rather than relying on established conventions.

Identify instances where newer code follows better practices than older code. These inconsistencies suggest opportunities for broad refactoring that would improve overall codebase quality beyond the immediate files under audit.

## Code Rewriting Workflow

After identifying style issues, systematically rewrite code to address them while preserving functionality.

### Step 1: Prioritize Issues by Impact

Not all style issues have equal importance. Prioritize fixes based on impact to functionality where security vulnerabilities demand immediate fixing, readability where confusing code causes comprehension failures, maintainability where poor structure impedes evolution, and performance where inefficiencies cause user-facing problems. Address high