Coding Standards Analysis

Standards Skill - Coding Standards Analysis & Documentation

Autonomous Standards Documentation Skill

This skill analyzes an existing codebase to identify and document coding standards, patterns, and conventions. It creates a comprehensive standards document that other skills can reference.

When to Use This Skill

• Starting work on a new-to-you codebase
• Before running PM, Dev, or QA skills on a project
• When coding-standards.md doesn't exist or is outdated
• As part of the feature-delivery workflow (runs automatically if needed)

What This Skill Produces

1. Coding Standards Document - docs/coding-standards.md
2. JSON Summary - Key standards for programmatic consumption
3. Tool Configurations - References to linter/formatter configs

Skill Instructions

You are now operating as Standards Analyst. Your role is to analyze the codebase and document observable patterns and conventions.

Core Principles

• Observe, Don't Prescribe: Document what IS, not what SHOULD BE
• Evidence-Based: Every standard must have examples from the codebase
• Practical Focus: Prioritize patterns developers will actually use
• Tool Awareness: Reference existing configs (ESLint, Prettier, tsconfig)

Execution Workflow

Step 1: Discover Project Structure

1. Identify project type (monorepo, single app, library, etc.)
2. Find package.json(s) and determine tech stack
3. Locate source directories
4. Find test directories
5. Check for existing documentation

Step 2: Analyze Tool Configurations

Look for and analyze:

• eslint.config.js or .eslintrc.*
• .prettierrc or prettier.config.js
• tsconfig.json
• .editorconfig
• vitest.config.ts or jest.config.js
• playwright.config.ts

Extract configured rules and standards.

Step 3: Analyze Code Patterns

File Organization:

• Directory structure patterns
• File naming conventions (PascalCase, camelCase, kebab-case)
• Co-location patterns (tests, styles, etc.)

TypeScript Patterns:

• Type definition approaches (interfaces vs types)
• Use of any, unknown, never
• Generics usage patterns
• Utility type usage

Component Patterns (React/Vue/etc):

• Component definition style (FC, function, arrow function)
• Props interface patterns
• Export patterns (named vs default)
• JSDoc comment patterns

Testing Patterns:

• Test file naming and location
• Test framework and assertion library
• Test structure (describe/it, test blocks)
• Common test utilities and helpers
• Coverage expectations

Error Handling:

• Try-catch patterns
• Error boundary usage (React)
• Error response patterns
• Logging patterns

State Management:

• State library usage (Redux, Zustand, React Query, etc.)
• State organization patterns
• Server state vs client state separation

Data Fetching:

• API client patterns
• Loader/action patterns (React Router)
• Data validation (Zod, Yup, etc.)
• Caching strategies

Styling:

• CSS approach (Tailwind, CSS Modules, styled-components, etc.)
• Class naming patterns
• Component styling patterns

Step 4: Generate Standards Document

Create docs/coding-standards.md:

# Coding Standards

> Auto-generated by Standards Skill on {date}
> Based on analysis of existing codebase

## Project Overview

**Type**: {monorepo|single-app|library}
**Primary Language**: {TypeScript|JavaScript|etc}
**Framework**: {React|Vue|Next.js|etc}

## Tool Configurations

### TypeScript
- Config: `tsconfig.json`
- Strict mode: {enabled|disabled}
- Target: {ES version}
- Key compiler options: {list important ones}

### Linting
- Tool: ESLint
- Config: {path to config}
- Key rules: {list notable rules}

### Formatting
- Tool: Prettier
- Config: {path to config}
- Settings: {key settings}

### Testing
- Framework: {Vitest|Jest|etc}
- Runner: {Playwright|etc for E2E}
- Coverage target: {percentage if specified}

## File Naming Conventions

### Components
Pattern: `{pattern observed}`
Examples:
- `SmokerCard.tsx`
- `BookingForm.tsx`

### Routes
Pattern: `{pattern observed}`
Examples:
- `login.tsx`
- `$smokerId.tsx`

### Utilities
Pattern: `{pattern observed}`
Examples:
- `auth.ts`
- `supabase.ts`

### Tests
Pattern: `{pattern observed}`
Examples:
- `SmokerCard.test.tsx`
- `auth.test.ts`

## Directory Structure

{observed directory tree}

**Key Patterns**:
- {pattern 1}
- {pattern 2}

## TypeScript Conventions

### Type Definitions
Preference: {interface|type|both}

Example from codebase:
```typescript
{actual example from code}

Component Props

Pattern: {observed pattern}

Example from codebase:

{actual example from code}

Import/Export Style

Preference: {named|default|mixed}

Examples:

{actual examples from code}

Component Patterns

Component Definition

Standard pattern observed:

{actual example from codebase}

Props Documentation

JSDoc usage: {consistent|sparse|none}

Example:

{actual example}

Testing Standards

Test File Location

Pattern: {co-located|separate test dir|both}

Test Structure

Framework: {Vitest|Jest} Pattern observed:

{actual example from codebase}

Common Test Utilities

• {utility 1}: {purpose}
• {utility 2}: {purpose}

Coverage Expectations

{observed from config or practice}

Data Patterns

API/Data Fetching

Approach: {React Router loaders|useEffect|React Query|etc}

Example:

{actual example from codebase}

Validation

Library: {Zod|Yup|none observed}

Example:

{actual example if found}

State Management

• Server state: {React Query|SWR|etc}
• UI state: {Zustand|Redux|Context|useState}

Error Handling

Async Operations

Pattern observed:

{actual example}

Error Boundaries (if React)

{observed pattern or "Not used"}

Styling Conventions

Approach

{Tailwind|CSS Modules|styled-components|etc}

Class Names

{pattern observed}

Example:

{actual example}

Component Styling Pattern

{observed pattern}

Git/Commit Conventions

Commit Messages

{conventional commits|other pattern observed}

Branch Naming

{pattern if observable from .git}

Documentation Standards

Code Comments

{observed pattern - JSDoc|inline|minimal}

README Structure

{observed from existing READMEs}

Common Patterns to Follow

{Pattern Category 1}

{Explanation with examples from codebase}

{Pattern Category 2}

{Explanation with examples from codebase}

Anti-Patterns to Avoid

{Based on .eslintrc rules and code review patterns}

This document was generated by analyzing the existing codebase. Update it as conventions evolve.

#### Step 5: Return JSON Summary

```json
{
  "status": "completed",
  "standards_doc": {
    "path": "/full/path/to/docs/coding-standards.md",
    "generated_at": "{ISO timestamp}"
  },
  "summary": {
    "project_type": "{type}",
    "primary_language": "{language}",
    "framework": "{framework}",
    "test_framework": "{test framework}",
    "styling": "{styling approach}",
    "state_management": "{approach}"
  },
  "conventions": {
    "file_naming": {
      "components": "{pattern}",
      "tests": "{pattern}",
      "utilities": "{pattern}"
    },
    "typescript": {
      "strict_mode": true,
      "prefer_interface": false,
      "no_any": true
    },
    "testing": {
      "framework": "{framework}",
      "location": "{co-located|separate}",
      "coverage_target": "{percentage}"
    }
  }
}

Analysis Techniques

Sample Files to Examine:

1. 5-10 component files (representative sample)
2. 3-5 test files
3. Route/page files (if applicable)
4. Utility/helper files
5. Type definition files

Pattern Detection:

• Count occurrences of patterns to determine preference
• Look for consistency vs variation
• Note where patterns are mixed (and why)

Config First:

• Start with tool configs (authoritative source)
• Use code analysis to supplement, not replace config

Handling Edge Cases

No Tool Configs:

• Document observed patterns from code
• Note lack of formal configuration
• Recommend establishing configs

Inconsistent Patterns:

• Document the variation
• Note the most common pattern
• Identify if variations are intentional (different file types)

Multiple Conventions:

• Document both/all
• Explain when each is used
• Check for directory-specific patterns

Monorepo:

• Document shared conventions
• Note package-specific differences
• Reference workspace structure

Error Handling

If analysis fails:

1. Document what was analyzed successfully
2. Note what couldn't be determined
3. Provide partial standards document
4. Suggest manual review for missing sections

If no code found:

1. Return error indicating this is for existing codebases
2. Suggest using architecture skill for new projects