rename-with-dates

name: rename-with-dates description: Rename documents and files (PDFs, images, screenshots, etc.) by reading their content to extract the effective/publication date, then renaming them with a "YYYY-MM-DD - Clear descriptive title.ext" format. Use when the user wants to organize files with date prefixes based on document content. argument-hint: '[directory or files]'

Rename Documents with Date Prefixes

Rename files in a folder by extracting the effective date from their content and giving them a clean, human-readable title.

Target format

YYYY-MM-DD - Clear descriptive title.ext

Title casing: capitalize only the first word and proper nouns (title case), like a sentence.

Examples:

• 2023-11-01 - General terms and conditions.pdf
• 2025-08-01 - Credit card fees and charges.pdf
• 2025-12-01 - Key facts statement - Term deposits.pdf
• 2024-06-15 - Rewards program earning structure.png
• 2024-03-01 - Schedule of charges.pdf

Supported file types

• PDFs: Read the first few pages (and last page if needed) to find dates and understand content
• Images / Screenshots (PNG, JPG, etc.): View the image to understand its content, then summarize it into a clear descriptive title. For screenshots, the date is often embedded in the filename (e.g., Screenshot 2026-01-12 at 11.07.33.png → date is 2026-01-12)
• Other documents: Read content where possible to extract dates and meaning

Workflow

1. List files in the target directory (default: current working directory, or $ARGUMENTS if provided)
2. Skip files that already follow the YYYY-MM-DD - Title.ext pattern (but offer to clean up their titles if needed)
3. Read each file to find the effective date and understand the content:
   • For PDFs:
     • Look for explicit "Effective from..." or "Effective date" statements — prefer these
     • Look for version dates in footers (e.g., "08/2025", "v. August 14, 2023")
     • Look for dated headers, cover pages, or document stamps
     • Use the effective/applicability date, not the publication or copyright date
   • For images/screenshots:
     • View the image to understand what it shows
     • Extract date from the original filename if it contains one (e.g., Screenshot 2026-01-12 at ...)
     • If the image contains visible dates in its content, prefer those
     • If no date can be found, ask the user
   • Match the date precision to what the document provides: use YYYY-MM-DD for exact dates, YYYY-MM for month-only, YYYY for year-only
4. Choose a clear title:
   • Use sentence case: capitalize only the first word and proper nouns
   • Be descriptive but concise (e.g., "Credit card fees and charges", not "popularbankname_credit_card_fees_charges")
   • For screenshots: summarize what the image shows (e.g., "Rewards program earning structure", "Account balance overview")
   • Keep well-known abbreviations uppercase: KFS, FAQ, T&C
   • Remove redundant institution names if the folder context already makes it clear
5. Present a summary table showing current name, detected date, and proposed new name
6. Rename all files after presenting the plan
7. Post-rename analysis — after renaming, scan the folder for cleanup opportunities and present a report with three sections:
   • Duplicates: Compare files with similar titles using MD5 checksums (md5 -r). Files with identical hashes are exact duplicates. Propose keeping one and trashing the others.
   • Superseded documents: Identify files that are older versions of the same document type (e.g., "Personal banking general T&C" from 2023 vs 2025). The newer version supersedes the older. Propose trashing the older version.
   • Expired documents: For time-bound documents (campaigns, offers, promotions) that specify a validity period (e.g., "1 November 2025 – 31 December 2025"), check if the end date has passed relative to today. Propose trashing expired ones. Do not flag standing T&Cs, KFS documents, or privacy policies — only documents with explicit campaign/offer end dates.
8. Verify by listing the final result

Multi-language PDF stripping

Many legal/banking documents repeat the same content translated across several languages, organized as consecutive blocks of pages (e.g., pages 1-10 in English, 11-20 in Arabic, 21-30 in Bulgarian). When detected, propose stripping to keep only English and French pages.

Detection

1. While reading a PDF, sample pages throughout the document (not just the beginning) to detect language blocks
2. A document qualifies for stripping only if:
   • The content is repeated in blocks of pages, each block being a full translation of the same content
   • Each page is in a single language — if a page mixes multiple languages (e.g., English and Arabic side by side, or bilingual tables), do NOT propose stripping that document
   • The granularity is the page: each page belongs to exactly one language
3. Identify the page ranges for each language block (e.g., "Pages 1-25: English, Pages 26-50: Arabic, Pages 51-75: French")

Proposal

• Present findings clearly: list each language detected and its page range
• Propose which pages to keep (English and French) and which to remove
• Ask the user for confirmation before modifying the PDF
• Use a tool like qpdf or pdftk to extract only the desired pages into a new file
• Replace the original file with the stripped version (or keep a backup if the user prefers)

When NOT to strip

• Pages contain multiple languages (bilingual layouts, side-by-side translations)
• The translations are not full-document blocks (e.g., just a translated summary at the end)
• The document has only one language
• You are not confident about the language boundaries

Required tools

This skill depends on third-party CLI tools. At the start of execution, check if each is available and propose to install any that are missing via brew install.

mdls (macOS built-in) can also be used for metadata and does not need installation.

If a missing tool is needed for the current run, propose the install command and ask the user before proceeding. If the tool is not needed (e.g., no multi-language PDFs detected, so qpdf is not required), skip silently.

Important rules

• Always extract dates from file content (or filename for screenshots), never from file system metadata
• For PDFs, read the first few pages (and last page if needed) to find the date
• For images, always view the image to produce a meaningful title — never just use the original filename
• If a document has both a publication date and an "Effective from" date, use the effective date
• If no date can be found in the content or filename, fall back to PDF metadata (CreationDate, ModDate) using mdls or exiftool. Only use file system dates (modification date) as a last resort
• If no date can be found at all, flag it to the user and ask what to do
• Use mv for renaming — never copy-and-delete