File Renamer

Overview

This skill performs intelligent file renaming to comply with CLAUDE.md standards. It transforms non-compliant filenames into properly structured names based on file type, content analysis, and user-provided categorization.

When to Use This Skill

• After filename validation identifies non-compliant files
• When organizing files from SORT/ directory
• As part of pre-commit hooks
• During repository cleanup operations
• When standardizing legacy file collections

Renaming Patterns by File Type

Image Files

Target Pattern: [org]-[product]-[descriptor]-[type]-[resolution]-[version].[format]

Transformation Steps:

1. Convert to lowercase
2. Replace spaces/underscores with hyphens
3. Remove special characters
4. Extract or prompt for: org, product, descriptor, type
5. Get resolution from image metadata or use original
6. Add version (default: v1-0)
7. Preserve/normalize file extension

Example Transformations:

Before: Bear_Market_Strategy__When_Competitors_Exit.png
After:  ths-stack-bear-market-strategy-infographic-1920x1080-v1-0.png

Before: TerraHash Logo Final (1).PNG
After:  terrahash-stack-logo-icon-512x512-v1-0.png

Before: Smart DIP Buying Banner.jpg
After:  ryno-crypto-smart-dip-buying-banner-1920x1080-v1-0.jpg

Before: Mining Process Diagram v2.svg
After:  terrahash-mining-mining-process-diagram-original-v2-0.svg

Document Files

Target Pattern: [org]-[product]-[category]-[title]-[version].[format]

Transformation Steps:

1. Convert to lowercase
2. Replace spaces/underscores with hyphens
3. Remove special characters
4. Extract or prompt for: org, product, category
5. Clean and truncate title (max 50 chars)
6. Add/normalize version
7. Preserve/normalize file extension

Example Transformations:

Before: TerraHash Mining Overview.pdf
After:  terrahash-mining-guide-overview-v1-0.pdf

Before: PRD - Smart Contract Implementation (Draft).docx
After:  ryno-crypto-prd-smart-contract-implementation-v1-0.docx

Before: API Documentation v3.txt
After:  ths-stack-api-docs-api-documentation-v3-0.txt

Before: Security Audit Report 2024-11-07.pdf
After:  ryno-crypto-security-audit-report-v1-0.pdf

Markdown Files

Target Pattern: [category]-[title]-[date-optional].md

Transformation Steps:

1. Convert to lowercase
2. Replace spaces/underscores with hyphens
3. Extract or prompt for category
4. Clean title
5. Add date if time-sensitive (YYYY-MM-DD format)
6. Ensure .md extension

Example Transformations:

Before: PRD Token Economics.md
After:  prd-token-economics.md

Before: Meeting Notes - Nov 7 2024.md
After:  meeting-notes-nov-7-2024-20241107.md

Before: Architecture Specs.MD
After:  specs-architecture.md

Before: Deployment Guide.markdown
After:  guide-deployment.md

Renaming Workflow

Phase 1: Pre-Rename Analysis

For each file to be renamed:

1. Determine File Type

   # Get file extension
   extension="${filename##*.}"
   
   # Categorize
   case $extension in
     png|jpg|jpeg|gif|svg|webp) type="image" ;;
     pdf|docx|txt|doc) type="document" ;;
     md|markdown) type="markdown" ;;
     *) type="other" ;;
   esac
   

2. Extract Image Metadata (for images)

   # Get image dimensions
   identify -format "%wx%h" image.png
   # Returns: 1920x1080
   

3. Analyze Content (for documents)

   # Extract text for categorization hints
   pdftotext document.pdf - | head -20
   # or for DOCX
   pandoc document.docx -t plain
   

4. Identify Existing Version

   • Look for patterns: v1, v2, version 1, final, draft
   • Extract semantic version if present
   • Default to v1-0 if not found

Phase 2: Component Gathering

Interactive Prompts (when needed)

For missing required components, use AskUserQuestion:

For Images:

**Renaming:** Original_Filename.png

Please provide the following information:

1. **Organization** (org):
   - ryno: Ryno Crypto Services
   - ths: TerraHash Stack
   - terrahash: TerraHash Mining

2. **Product** (product):
   - crypto: Crypto services
   - stack: TerraHash Stack platform
   - mining: Mining operations

3. **Descriptor** (descriptor):
   - Brief description (e.g., "logo", "banner", "architecture")

4. **Image Type** (type):
   - banner: Wide marketing banner
   - logo: Logo/branding
   - icon: Icon/small graphic
   - infographic: Informational graphic
   - diagram: Technical diagram
   - screenshot: Screenshot
   - hero: Hero image

**AI-Suggested Values** (based on content analysis):
- org: ths (detected "TerraHash Stack" in filename)
- product: stack
- descriptor: bear-market-strategy
- type: infographic

For Documents:

**Renaming:** Document_Name.pdf

Please provide:

1. **Organization** (org): ryno | ths | terrahash

2. **Product** (product): crypto | stack | mining

3. **Category** (category):
   - prd: Product Requirements Document
   - specs: Technical Specifications
   - guide: User/Developer Guide
   - api-docs: API Documentation
   - whitepaper: Whitepaper
   - security: Security Documentation

**AI-Suggested Values**:
- org: ryno
- product: crypto
- category: guide

Automated Component Extraction

Use filename analysis and AI to suggest values:

def extract_components(filename, file_type):
    """Extract components from filename using heuristics"""

    lower_name = filename.lower()
    components = {}

    # Organization detection
    if 'terrahash' in lower_name or 'ths' in lower_name:
        components['org'] = 'ths'
        components['product'] = 'stack'
    elif 'ryno' in lower_name:
        components['org'] = 'ryno'
        components['product'] = 'crypto'

    # Type detection (images)
    if 'logo' in lower_name:
        components['type'] = 'logo'
    elif 'banner' in lower_name:
        components['type'] = 'banner'
    elif 'diagram' in lower_name or 'architecture' in lower_name:
        components['type'] = 'diagram'
    elif 'infographic' in lower_name or 'chart' in lower_name:
        components['type'] = 'infographic'

    # Category detection (documents)
    if 'prd' in lower_name or 'requirements' in lower_name:
        components['category'] = 'prd'
    elif 'spec' in lower_name:
        components['category'] = 'specs'
    elif 'guide' in lower_name or 'tutorial' in lower_name:
        components['category'] = 'guide'
    elif 'api' in lower_name:
        components['category'] = 'api-docs'
    elif 'whitepaper' in lower_name:
        components['category'] = 'whitepaper'

    # Version detection
    version_match = re.search(r'v(\d+)[-_.]?(\d+)?[-_.]?(\d+)?', lower_name)
    if version_match:
        major = version_match.group(1)
        minor = version_match.group(2) or '0'
        patch = version_match.group(3) or '0'
        components['version'] = f'v{major}-{minor}-{patch}'
    else:
        components['version'] = 'v1-0'

    return components

Phase 3: Name Construction

Build New Filename

def construct_filename(file_type, components, original_filename):
    """Construct compliant filename from components"""

    # Sanitize descriptor/title
    def sanitize(text):
        # Convert to lowercase
        text = text.lower()
        # Replace spaces and underscores with hyphens
        text = re.sub(r'[\s_]+', '-', text)
        # Remove special characters
        text = re.sub(r'[^a-z0-9-]', '', text)
        # Remove consecutive hyphens
        text = re.sub(r'-+', '-', text)
        # Trim hyphens from edges
        text = text.strip('-')
        # Limit length
        if len(text) > 50:
            text = text[:50].rstrip('-')
        return text

    extension = original_filename.split('.')[-1].lower()

    if file_type == 'image':
        # [org]-[product]-[descriptor]-[type]-[resolution]-[version].[format]
        new_name = f"{components['org']}-{components['product']}-"
        new_name += f"{sanitize(components['descriptor'])}-{components['type']}-"
        new_name += f"{components['resolution']}-{components['version']}.{extension}"

    elif file_type == 'document':
        # [org]-[product]-[category]-[title]-[version].[format]
        new_name = f"{components['org']}-{components['product']}-"
        new_name += f"{components['category']}-{sanitize(components['title'])}-"
        new_name += f"{components['version']}.{extension}"

    elif file_type == 'markdown':
        # [category]-[title]-[date-optional].md
        new_name = f"{components['category']}-{sanitize(components['title'])}"
        if 'date' in components:
            new_name += f"-{components['date']}"
        new_name += ".md"

    return new_name

Validate New Filename

Before renaming, validate the constructed filename:

def validate_new_filename(new_filename):
    """Ensure new filename meets all requirements"""

    checks = {
        'lowercase': new_filename == new_filename.lower(),
        'no_spaces': ' ' not in new_filename,
        'no_special_chars': not re.search(r'[^a-z0-9.-]', new_filename),
        'length_ok': len(new_filename) <= 100,
        'has_extension': '.' in new_filename,
        'has_version': re.search(r'v\d+-\d+', new_filename) is not None
    }

    all_valid = all(checks.values())

    return all_valid, checks

Phase 4: Execute Rename

Safety Checks

Before renaming:

1. Check for conflicts

   if [ -f "new_filename.ext" ]; then
       echo "ERROR: File already exists: new_filename.ext"
       # Prompt user for action: overwrite, rename, skip
   fi
   

2. Create backup list

   echo "old_filename.ext -> new_filename.ext" >> SORT/rename_log.txt
   

3. Dry run option

   • Show all proposed renames
   • Ask for confirmation before executing

Perform Rename

# Use git mv if in git repository (preserves history)
if git rev-parse --git-dir > /dev/null 2>&1; then
    git mv "old_filename.ext" "new_filename.ext"
else
    mv "old_filename.ext" "new_filename.ext"
fi

Post-Rename Validation

# Verify file exists at new location
if [ -f "new_filename.ext" ]; then
    echo "✅ Successfully renamed: old_filename.ext -> new_filename.ext"
else
    echo "❌ Rename failed: old_filename.ext"
fi

Batch Renaming

Process Multiple Files

#!/bin/bash

RENAME_LOG="SORT/batch_rename_$(date +%Y%m%d_%H%M%S).log"

echo "Batch Rename Log - $(date)" > "$RENAME_LOG"
echo "===========================================" >> "$RENAME_LOG"

# For each file in SORT/
find SORT/ -type f | while read file; do
    filename=$(basename "$file")

    # Skip if already compliant
    if [[ $filename =~ ^[a-z0-9-]+\.[a-z]+$ ]]; then
        echo "SKIP: $filename (already compliant)" >> "$RENAME_LOG"
        continue
    fi

    # Analyze and rename
    echo "PROCESSING: $filename" >> "$RENAME_LOG"

    # ... renaming logic ...

    echo "RENAMED: $filename -> $new_filename" >> "$RENAME_LOG"
done

echo "===========================================" >> "$RENAME_LOG"
echo "Batch rename complete. See log: $RENAME_LOG"

Progress Tracking

total_files=$(find SORT/ -type f | wc -l)
current=0

find SORT/ -type f | while read file; do
    ((current++))
    progress=$((current * 100 / total_files))
    echo "[$progress%] Processing: $(basename "$file")"
    # ... renaming logic ...
done

Integration with Other Skills

Works With filename-validator

# 1. Run validator first
filename-validator SORT/

# 2. Get list of invalid files from validation report
# 3. For each invalid file, run renamer
# 4. Validate renamed files

Works With file-relocator

# 1. Rename files in place
file-renamer SORT/

# 2. Then relocate to correct directories
file-relocator SORT/

Used By file-organizer

# Main orchestrator uses renamer as part of workflow
file-organizer SORT/
  -> validate files
  -> rename files (this skill)
  -> relocate files
  -> run OPSEC agents

Special Cases

Handling Duplicates

If renamed file conflicts with existing file:

Option 1: Increment version

existing: ths-stack-logo-icon-512x512-v1-0.png
new:      ths-stack-logo-icon-512x512-v1-1.png

Option 2: Add suffix

existing: ryno-crypto-guide-overview-v1-0.pdf
new:      ryno-crypto-guide-overview-alt-v1-0.pdf

Option 3: User prompt

Conflict detected:
  Existing: ths-stack-logo-icon-512x512-v1-0.png
  New:      ths-stack-logo-icon-512x512-v1-0.png

Actions:
1. Overwrite existing file
2. Rename new file (add version/suffix)
3. Keep both (manual review)
4. Skip this file

Choose action [1-4]:

Preserving Dates

For time-sensitive files:

# Extract date from original filename
original="Security_Audit_Nov_7_2024.pdf"
# Parse date
date="20241107"
# Include in new filename
new="ryno-crypto-security-audit-report-${date}-v1-0.pdf"

Multi-Version Files

When multiple versions exist:

File_v1.pdf -> ryno-crypto-guide-overview-v1-0.pdf
File_v2.pdf -> ryno-crypto-guide-overview-v2-0.pdf
File_Final.pdf -> ryno-crypto-guide-overview-v3-0.pdf (assumed latest)

Output and Reporting

Rename Summary Report

# File Rename Report

**Date:** 2025-11-21T10:30:00Z
**Files Processed:** 25
**Files Renamed:** 18
**Files Skipped:** 5 (already compliant)
**Errors:** 2

## Successfully Renamed Files

1. ✅ `Bear_Market_Strategy.png` → `ths-stack-bear-market-strategy-infographic-1920x1080-v1-0.png`
2. ✅ `TerraHash Logo.PNG` → `terrahash-stack-logo-icon-512x512-v1-0.png`
3. ✅ `PRD Smart Contract.pdf` → `ryno-crypto-prd-smart-contract-v1-0.pdf`

## Skipped Files (Already Compliant)

1. ⏭️  `ryno-crypto-logo-icon-512x512-v1-0.png`
2. ⏭️  `ths-stack-prd-tokenomics-v1-0.pdf`

## Errors

1. ❌ `locked_file.pdf` - File is locked or in use
2. ❌ `corrupted_image.png` - Cannot read image metadata

## Rename Log

Full details saved to: `SORT/rename_log_20251121_103000.txt`

Detailed Log File

2025-11-21 10:30:15 | START | Batch rename operation started
2025-11-21 10:30:16 | ANALYZE | Bear_Market_Strategy.png
2025-11-21 10:30:16 | EXTRACT | Detected: org=ths, product=stack, type=infographic
2025-11-21 10:30:16 | METADATA | Resolution: 1920x1080
2025-11-21 10:30:17 | RENAME | Bear_Market_Strategy.png -> ths-stack-bear-market-strategy-infographic-1920x1080-v1-0.png
2025-11-21 10:30:17 | VERIFY | ✅ File renamed successfully
2025-11-21 10:30:18 | COMPLETE | Batch rename operation completed

Error Handling

Common Issues and Solutions

File locked or in use:

if lsof "$filename" > /dev/null 2>&1; then
    echo "WARNING: File is in use: $filename"
    echo "Close the file and try again"
fi

Permission denied:

if [ ! -w "$filename" ]; then
    echo "ERROR: No write permission for: $filename"
    chmod u+w "$filename"  # or prompt for sudo
fi

Invalid characters in path:

# Sanitize the entire path
safe_path=$(echo "$path" | tr ' ' '-' | tr '[:upper:]' '[:lower:]')

Quality Assurance Checklist

Before marking rename operation complete:

• ✅ All files validated before renaming
• ✅ User prompted for missing components (interactive mode)
• ✅ No filename conflicts created
• ✅ All renames logged
• ✅ Renamed files validated against CLAUDE.md standards
• ✅ Backup/rollback information saved
• ✅ Report generated with full details
• ✅ No files lost or corrupted

---

Related Documentation:

• CLAUDE.md (File naming conventions - source of truth)
• .claude/skills/filename-validator/skill.md (Use this first)
• .claude/skills/file-relocator/skill.md (Use this after renaming)
• .claude/skills/file-organizer/skill.md (Main orchestrator)
• .claude/agents/organization-sanitation-agent.md (Final validation)