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 a tk ticket tagged audit with the report as its body. Use todos_oneshot(title: "Audit: Naming conventions", description: "<report content>", tags: "audit", type: "task") .

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

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: tk ticket (tagged audit)

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.