code-style-review

name	code-style-review
description	Document coding conventions, patterns, and guidelines for an existing codebase. Use when onboarding to a new project to understand its coding style, or when creating style documentation for team reference.

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}

---

## Writing Guidelines

1. **Evidence-based:** Every pattern should have a file path reference
2. **Examples:** Include actual code snippets from the codebase
3. **Neutral tone:** Describe what exists, not what's "right" or "wrong"
4. **Actionable:** Someone should be able to write conforming code after reading
5. **Concise:** Keep under 400 lines - trim if needed

## Section Priority

**Always include:**
- Naming Conventions
- File Organization
- Code Patterns (at least 2-3 patterns)
- Do's and Don'ts

**Include when relevant:**
- Import Style (especially for larger codebases)
- Error Handling (if patterns are consistent)
- Testing (if tests exist)
- Tooling (if configs exist)

**Optional:**
- Inconsistencies Noted (when conducting an audit)

## Common Pitfalls

- ❌ Prescribing changes instead of documenting reality
- ❌ No code examples (patterns need concrete examples)
- ❌ Missing file paths (where did you see this pattern?)
- ❌ Too verbose (this is a reference doc, not a tutorial)
- ❌ Ignoring existing linter/formatter configs