file-name-wizard

name	file-name-wizard
description	Audit all filename and naming conventions in the codebase against AGENTS.md standards and common patterns. Use when user asks to check naming conventions, audit filenames, find naming inconsistencies, or validate file naming patterns.

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
| 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.