Filename & Naming Convention Audit

Instructions

Perform systematic audit of all filenames and naming conventions in the codebase to identify inconsistencies, anti-patterns, and violations of naming standards.

Phase 1: Discovery & Standard Extraction

Step 1: Find All Files

Use Glob to identify all files in the codebase:

• Source files (.ts, .tsx, .js, .jsx, etc.)
• Config files
• Documentation files
• Test files

Create comprehensive todo list of all files to audit.

Step 2: Extract Naming Standards

Read all AGENTS.md files in the repository:

• Root AGENTS.md if exists
• Directory-specific AGENTS.md files

Extract naming conventions:

• File naming patterns (kebab-case, PascalCase, etc.)
• Directory structure rules
• Component naming rules
• Utility/helper naming rules
• Test file naming rules
• Config file naming rules
• Constant/enum file naming rules

Step 3: Identify Implicit Patterns

Even without explicit AGENTS.md rules, identify patterns:

• Most common naming convention in each directory
• Grouping patterns (e.g., *.service.ts, *.controller.ts)
• Organizational patterns (e.g., components/, utils/, lib/)

Phase 2: Systematic File Audit

For EACH file in the todo list:

Step 1: Analyze Filename

• What is the current filename?
• What naming convention does it use?
• Is it descriptive and clear?
• Does it match its purpose/content?

Step 2: Check Against Standards

Compare to:

• Explicit AGENTS.md rules for this directory
• Implicit patterns in the same directory
• Common naming conventions for file type
• Best practices for the framework/language

Step 3: Identify Issues

Naming Convention Violations:

• Wrong case (e.g., PascalCase when should be kebab-case)
• Mixed conventions (e.g., userAuth.service.ts mixing camelCase and dot notation)
• Inconsistent with directory pattern

Clarity Issues:

• Vague names (e.g., utils.ts, helpers.ts, stuff.ts)
• Overly verbose names
• Misleading names (content doesn’t match name)
• Abbreviations without context

Anti-Patterns:

• Temporary names (e.g., temp.ts, test.ts, new-*.ts, *-v2.ts)
• Generic names (e.g., index2.ts, common.ts)
• Dated names (e.g., old-*.ts, legacy-*.ts)
• Feature flag names (e.g., *-new.ts, *-enhanced.ts)

Organizational Issues:

• File in wrong directory
• Missing grouping suffix (e.g., should be *.service.ts)
• Inconsistent with sibling files

Step 4: Check File Contents

Read the file to verify:

• Does filename accurately describe contents?
• Would a better name exist based on what’s inside?
• Are there naming conventions violations inside (class names, etc.)?

Step 5: Record Findings

Store in memory:

File: path/to/filename.ts
Convention Used: camelCase
Should Be: kebab-case
Pattern: Violates directory convention
Issues:
- [Specific issue]
Suggested Name: [better-name.ts]
Severity: [HIGH|MEDIUM|LOW]

Step 6: Update Todo

Mark file as audited in todo list.

Phase 3: Pattern Analysis

After auditing all files:

Step 1: Identify Systemic Issues

• Which directories have most inconsistencies?
• What naming patterns are most violated?
• Are there clusters of similar violations?

Step 2: Find Outliers

• Files that don’t match any pattern
• One-off naming schemes
• Orphaned file types

Step 3: Detect Missing Standards

• Directories lacking clear naming conventions
• File types without established patterns
• Areas needing AGENTS.md documentation

Phase 4: Generate Report

Create report at .audits/naming-audit-[timestamp].md:

# Filename & Naming Convention Audit
**Date**: [timestamp]
**Files Audited**: X
**Issues Found**: Y

---

## Executive Summary
- **Critical Issues**: X (blocks consistency)
- **High Priority**: Y (major violations)
- **Medium Priority**: Z (minor inconsistencies)
- **Low Priority**: W (suggestions)

**Most Problematic Directory**: [path] (X issues)

---

## Issues by Severity

### CRITICAL: Convention Violations

#### Temporary/Migration Filenames
- `src/services/auth-v2.ts` - Migration file still in use
  - **Violates**: No version suffixes rule
  - **Suggested**: `src/services/auth.ts` (replace old one)

- `src/utils/new-logger.ts` - Temporary naming
  - **Violates**: No "new-" prefix rule
  - **Suggested**: `src/utils/logger.ts`

#### Wrong Case Convention
- `src/components/UserProfile.tsx` - PascalCase
  - **Directory Standard**: kebab-case
  - **Suggested**: `src/components/user-profile.tsx`

### HIGH: Consistency Violations

#### Inconsistent with Directory Pattern
- `src/services/database.ts` - Missing `.service.ts` suffix
  - **Pattern**: All files in directory use `*.service.ts`
  - **Suggested**: `src/services/database.service.ts`

#### Vague/Generic Names
- `src/utils/helpers.ts` - Too generic
  - **Contains**: String manipulation functions
  - **Suggested**: `src/utils/string-helpers.ts`

### MEDIUM: Clarity Issues

#### Misleading Names
- `src/lib/validator.ts` - Named as single purpose
  - **Contains**: Multiple validators and formatters
  - **Suggested**: Split or rename to `validators.ts`

### LOW: Suggestions

#### Verbose Names
- `src/components/user-authentication-form-component.tsx`
  - **Redundant**: "component" suffix in components dir
  - **Suggested**: `src/components/user-auth-form.tsx`

---

## Issues by Directory

### src/services/ (12 issues)
- **Pattern**: Should use `*.service.ts` suffix
- **Violations**:
  - `database.ts` (missing suffix)
  - `auth-helper.ts` (wrong suffix)
  - `userService.ts` (wrong case)

### src/components/ (8 issues)
- **Pattern**: kebab-case without suffix
- **Violations**:
  - `UserProfile.tsx` (PascalCase)
  - `button-component.tsx` (redundant suffix)

[Continue for all directories]

---

## Pattern Analysis

### Most Common Violations
1. **Mixed case conventions** - 15 files
2. **Missing pattern suffixes** - 12 files
3. **Generic names** - 8 files
4. **Temporary names** - 5 files

### Directories Lacking Standards
- `src/lib/` - No clear convention (mix of all patterns)
- `src/shared/` - Inconsistent organization
- `tools/` - No established pattern

### Emerging Anti-Patterns
- Version suffixes appearing (`*-v2`, `*-new`)
- Component files with "component" in name
- Service files without `.service.ts` suffix

---

## AGENTS.md Coverage

### Documented Standards
- ✅ `src/components/` - Documented in `src/AGENTS.md`
- ✅ `src/services/` - Documented in `src/AGENTS.md`
- ❌ `src/lib/` - No documentation
- ❌ `src/utils/` - No documentation
- ❌ `tools/` - No documentation

### Missing Documentation Needed
- File naming conventions for `src/lib/`
- Grouping patterns for utilities
- Test file naming standards
- Config file organization rules

---

## Statistics

**By Issue Type**:
- Case Violations: X
- Pattern Violations: Y
- Generic Names: Z
- Temporary Names: W
- Misleading Names: V

**By Severity**:
- Critical: X
- High: Y
- Medium: Z
- Low: W

**By File Type**:
- TypeScript: X issues
- React Components: Y issues
- Test Files: Z issues
- Config Files: W issues

---

## Detailed File List

### Critical Issues
| File | Issue | Suggested Name | Reason |
|------|-------|----------------|--------|
| `src/auth-v2.ts` | Version suffix | `src/auth.ts` | Migration files not allowed |
| `src/UserProfile.tsx` | Wrong case | `src/user-profile.tsx` | Directory uses kebab-case |

### High Priority Issues
[Similar table]

### Medium Priority Issues
[Similar table]

### Low Priority Issues
[Similar table]

Phase 5: Summary for User

Provide concise summary:

# Naming Convention Audit Complete

## Overview
- **Files Audited**: X
- **Issues Found**: Y
- **Directories with Issues**: Z

## Critical Issues (Immediate Action)
- X files with version/migration suffixes (`*-v2`, `*-new`)
- Y files with wrong case convention
- Z files in wrong locations

## Most Problematic Areas
1. **src/services/** - 12 issues (missing `.service.ts` suffix)
2. **src/components/** - 8 issues (case convention mix)
3. **src/lib/** - 6 issues (no clear standard)

## Top Violations
- Mixed case conventions: 15 files
- Missing pattern suffixes: 12 files
- Generic names: 8 files

## Missing Standards
- `src/lib/` lacks naming documentation
- `src/utils/` needs pattern definition
- Test files need naming standard

**Full Report**: `.audits/naming-audit-[timestamp].md`

Critical Principles

• NEVER EDIT FILES – This is audit only, not renaming
• NEVER SKIP FILES – Audit every file in todo list
• DO READ AGENTS.MD – Extract explicit standards first
• DO IDENTIFY PATTERNS – Find implicit conventions
• DO BE CONSISTENT – Apply same standards across similar files
• DO CHECK CONTENTS – Verify name matches file contents
• DO TRACK PROGRESS – Update todo list as you audit
• DO FLAG ANTI-PATTERNS – Especially temporary/migration names

Success Criteria

A complete naming audit includes:

• All files in codebase audited
• All AGENTS.md standards extracted and applied
• Implicit patterns identified for each directory
• Violations categorized by severity
• Systemic issues identified
• Missing standards documented
• Structured report generated
• Statistics and trends analyzed

After completing the audit, follow handbook 15.04 to create tk tickets for all surfaced issues.