file-name-wizard

SKILL.md

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.