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.mdif exists - Directory-specific
AGENTS.mdfiles
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.tsmixing 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
| 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**: 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.