code-style-review

Code Style Review Skill

Create code style documentation that captures coding conventions, patterns, and guidelines for an existing codebase.

When to Use This Skill

• Onboarding to an unfamiliar codebase
• Creating style documentation for team reference
• Understanding patterns before contributing
• Documenting conventions that aren't captured in linter configs

Don't use for:

• High-level architecture (use architecture-review skill)
• Planning new features (use feature-design skill)

File Location

Code style reviews live in the dev-plans repository:

dev-plans/
└── {project}/
    └── architecture/
        ├── YYYY-MM-DD-architecture.md
        └── YYYY-MM-DD-code-style.md

Naming: YYYY-MM-DD-code-style.md

Analysis Process

1. Gather Evidence

Before writing, examine:

Config files:

• .eslintrc*, eslint.config.* - Linting rules
• .prettierrc*, prettier.config.* - Formatting rules
• tsconfig.json - TypeScript settings
• biome.json, ruff.toml, etc. - Other linters/formatters

Sample code:

• 3-5 core source files
• 2-3 test files
• Entry points and exports

Existing docs:

• CONTRIBUTING.md
• STYLE.md or similar
• README sections on code style

2. Observe, Don't Prescribe

Document what IS, not what should be:

• Note inconsistencies without judgment
• Include examples from actual code
• Reference file paths for patterns

---

Document Template

# Code Style: {Project Name}

**Analyzed:** YYYY-MM-DD
**Codebase:** {path or repo}

---

## Naming Conventions

### Files and Directories

[How are files named? kebab-case, camelCase, PascalCase?]

- Source files: `{pattern}` (e.g., `user-service.ts`)
- Test files: `{pattern}` (e.g., `user-service.test.ts`)
- Component files: `{pattern}` (if applicable)
- Directories: `{pattern}`

### Functions and Methods

[Naming patterns for functions]

```typescript
// Example from codebase

Classes and Types

[Naming patterns for classes, interfaces, types]

// Example from codebase

Variables and Constants

• Variables: {pattern} (e.g., camelCase)
• Constants: {pattern} (e.g., SCREAMING_SNAKE_CASE)
• Private members: {pattern} (e.g., _prefixed or #private)

---

File Organization

Directory Structure Pattern

src/
├── {pattern}/     # {what goes here}
├── {pattern}/     # {what goes here}
└── {pattern}/     # {what goes here}

File Structure Pattern

[How are individual files typically organized?]

// 1. Imports (grouped how?)
// 2. Types/interfaces
// 3. Constants
// 4. Main exports
// 5. Helper functions

Module Boundaries

[How are modules separated? Barrel exports? Index files?]

---

Import Style

Grouping

[How are imports organized?]

// Example showing import organization

Preferred Patterns

• Absolute vs relative imports: {pattern}
• Barrel imports: {used/not used}
• Type imports: {inline vs separate}

---

Code Patterns

Common Patterns

{Pattern Name}

Where used: {locations}

// Example from codebase

{Pattern Name}

Where used: {locations}

// Example from codebase

Async Patterns

[How is async code typically written?]

// Example

State Management (if applicable)

[Patterns for managing state]

---

Error Handling

Error Types

[What error types/classes are used?]

// Example

Throwing Errors

[Pattern for throwing errors]

Catching Errors

[Pattern for catching and handling errors]

Logging

[How is logging done? What levels? What format?]

// Example

---

Testing

Test File Location

• Pattern: {where tests live}
• Naming: {test file naming pattern}

Test Structure

// Example test structure from codebase

Mocking Patterns

[How are mocks typically done?]

What Gets Tested

[Unit tests? Integration tests? What's the focus?]

---

Tooling

Linter

• Tool: {ESLint, Biome, etc.}
• Config: {path to config}
• Key rules: {notable enabled/disabled rules}

Formatter

• Tool: {Prettier, Biome, etc.}
• Config: {path to config}
• Key settings: {tab width, quotes, etc.}

Type Checking

• Config: {path to tsconfig}
• Strictness: {strict mode? key compiler options}

Pre-commit

[Any pre-commit hooks? Husky? lint-staged?]

---

Do's and Don'ts

Do

• [Pattern to follow]
• [Pattern to follow]
• [Pattern to follow]

Don't

• [Anti-pattern to avoid]
• [Anti-pattern to avoid]
• [Anti-pattern to avoid]

---

Inconsistencies Noted

[Any inconsistencies observed in the codebase - not judgmental, just factual]

• {inconsistency 1}
• {inconsistency 2}