abhiroopb/organizing-downloads

Organizing Downloads

Scans the local filesystem at C:\Users\basua\Dropbox\Downloads, identifies each file's content, and moves/renames it according to the rules below.

Filesystem Strategy

• Use the local filesystem (run_command with PowerShell) for all scanning, moving, and renaming.
• Path Handling: Always use absolute Windows paths with backslashes.
• Do NOT use the Dropbox MCP API for file operations.

Automation Script

An automated Python script is provided at scripts/organize.py inside the skill directory. This script extracts text from PDFs, applies the classification rules, handles binary hash deduplication, dynamically resolves target folder paths, and generates the required summary.

• To run a Dry Run (Preview):

  python scripts/organize.py
  

• To Execute the Organization (after user approval):

  python scripts/organize.py --execute
  

• To Rollback / Undo the last execution:

  python scripts/organize.py --undo
  

Key Script Features:

• Dynamic Resolution: Scans the Dropbox tree structures at start-up to dynamically discover correct folder paths based on keywords (e.g. matching account numbers or names).
• Current-Year Archiving & Auto-New-Year Transition: For bank statements and payslips, current-year files go directly into the root folder. When a new year begins, the script automatically detects and moves past-year statements/payslips still sitting in the root into their respective {YEAR}\ archive subfolders. (Receipts always go to Receipts\{YEAR}\).
• Conflict Prompting: If a file with the same name exists at target but has different content (hash), the user is prompted interactively to Overwrite (o), Rename with suffix (r), or Skip (s).
• Audit History: Executed runs are logged in .organized_history.json and deleted files are temporarily stored in .trash/ to allow seamless rollback.
• Fail-Safe & Bootstrapping: Safely skips browser placeholder files (.crdownload, .tmp, .part), catches lock permission errors (PermissionError), and automatically installs missing Python dependencies (like pypdf) at runtime.

Execution Workflow

1. Inventory & Classification: Use the scripts/organize.py script (without arguments) to scan and classify files in C:\Users\basua\Dropbox\Downloads.
2. Verify & Customize:
   • Step A: Verify proposed names/folders. Ensure they match the rules described below.
   • Step B: Handle Custom User Requests. Adjust classifications if the user asks for specific destination shifts (e.g. moving templates to Stremio or deleting particular files).
3. Summary & Approval:
   • MANDATORY: Present a numbered table with columns: #, Original Filename, New Name, Destination Folder, and Rationale.
   • MANDATORY: Highlight if any file is being replaced or if any new folder is being created.
   • MANDATORY: Wait for explicit user confirmation before proceeding.
4. Action: Upon user approval, run python scripts/organize.py --execute to execute the file operations.
5. Rollback if needed: If any file was organized incorrectly, run python scripts/organize.py --undo.

General Guidelines

• Naming: Date format is always YYYY-MM-DD.
• Date Source: Extract dates from the "Statement Date" field if available. Do not use file modification date unless no other date exists.
• Ignore Folders: ALWAYS ignore folders within the Downloads directory. Only process files.
• Ignore Subfolders: Only process files at the top level of the Downloads folder.
• Folder Creation: Follow established patterns. Do NOT create year folders for Utilities or Zareen's medical bills.
• Description: For medical/health bills, always include a brief description of the service (e.g., "Sutter Bill for Injured Elbow").

Rules

Rule 1: Purchase Receipts (Non-Home)

• Destination: C:\Users\basua\Dropbox\Money\Receipts\{YEAR}\
• Naming: YYYY-MM-DD - Item Name (Business Name).pdf
• Note: Verify items carefully from content text extraction (e.g. distinguishing a "Paisley Cotton Bandana" from a "Cotton Shirt" for Boggi Milano; using NordVPN, REI, SP Connect, or Sony/Best Buy as business/brand names).

Rule 2: Home Contractor Documents (2424 Tulare Ave)

• Destination: C:\Users\basua\Dropbox\Documents\2424 Tulare Ave\Contractors\{Contractor Name}\
• Naming: YYYY-MM-DD - Description.pdf

Rule 3: Bank & Brokerage Statements

• Destination: C:\Users\basua\Dropbox\Money\Banks\{Bank Name}\{Account Folder}\Statements\
• Naming: YYYY-MM-DD.pdf (statement end date).
• Note: For the active/current year, statements are stored directly in the account root folder, while past completed years are grouped in {YEAR}\ subfolders.
• Exceptions: Do not use \Statements subfolders for:
  • Chase DoorDash Card: C:\Users\basua\Dropbox\Money\Banks\Chase\DoorDash Card (8900)\
  • Chase Amazon Card: C:\Users\basua\Dropbox\Money\Banks\Chase\Amazon Card (9951)\
  • Chase CPC Checking: C:\Users\basua\Dropbox\Money\Banks\Chase\CPC Checking (822920638)\
  • Chase CPC Savings: C:\Users\basua\Dropbox\Money\Banks\Chase\CPC Savings (3760199860)\
• Specific Account Mapping:
  • Charles Schwab: Check the suffix to map correctly (e.g. 123 -> 5003-4123 - AB Roth IRA\Statements). Some folders use \Statement (singular) instead of \Statements (plural) based on precedent.

Rule 4: Bill Payments

• Destination: C:\Users\basua\Dropbox\Money\Banks\{Bank Name}\{Account Folder}\Bill Payment\ (or \Bill Payments\)
• Naming: YYYY-MM-DD.pdf
• Exception: Do not add "- payment" or any other suffix. Only use the date the file was paid on.

Rule 5: E-Trade (RSU + ESPP)

• Statements: C:\Users\basua\Dropbox\Money\Banks\E-Trade\Statements\
• Trade/Release/Payout Confirmations: C:\Users\basua\Dropbox\Money\Banks\E-Trade\RSU + ESPP\
• Naming: Ensure all confirmations have a unique name (e.g., YYYY-MM-DD - Release - 100 shares.pdf or YYYY-MM-DD - Trade - 50 shares (2).pdf).

Rule 6: Utilities (2424 Tulare Ave)

• Destination: C:\Users\basua\Dropbox\Documents\2424 Tulare Ave\Utilities\{Utility Name}\
• Naming: YYYY-MM-DD.pdf
• EBSAN: EBSAN\Statement\.
• EBMUD: EBMUD\.
• PG&E: PG&E\Electric and Gas Statements\.
• Sonic: Sonic\.

Rule 7: Home & Mortgage (2424 Tulare Ave)

• Mortgage Payments: C:\Users\basua\Dropbox\Documents\2424 Tulare Ave\Mortgage\Payments\
• Home Insurance: C:\Users\basua\Dropbox\Documents\2424 Tulare Ave\Home Insurance\ (e.g., YYYY-MM-DD - 2026 Policy Renewal.pdf).

Rule 8: Insurance & Health

• Aetna EOBs (Zareen): C:\Users\basua\Dropbox\Documents\Health\Zareen\Bill Payments\YYYY-MM-DD - Aetna EOB.pdf.
• Aetna EOBs (Abhi): C:\Users\basua\Dropbox\Documents\Health\Abhi\Bills\YYYY-MM-DD - Aetna EOB.pdf.
• Dental EOBs (Abhi): C:\Users\basua\Dropbox\Documents\Health\Abhi\Dental\YYYY-MM-DD - Delta Dental.pdf (No "EOB" in name).
• Health Visits (Abhi): C:\Users\basua\Dropbox\Documents\Health\Abhi\Visits\YYYY-MM-DD - Description.pdf.
• Bill Payments (Zareen): C:\Users\basua\Dropbox\Documents\Health\Zareen\Bill Payments\YYYY-MM-DD - Description.pdf. (No "Health" prefix, no year folders).

Rule 9: Pay Stubs & Employment

• Destination: C:\Users\basua\Dropbox\Money\Payslips\Abhi\{YEAR}\
• Naming: YYYY-MM-DD.pdf.
• Note: For the active/current year, files are stored directly in the root of Abhi\, while completed past years are grouped in {YEAR}\ subfolders.

Rule 10: Car & Transport

• FasTrak: C:\Users\basua\Dropbox\Documents\Car\FasTrak\YYYY-MM-DD.pdf.
• Tickets: C:\Users\basua\Dropbox\Documents\Car\Tickets\
  • Naming: YYYY-MM-DD - Description (Vendor).pdf or YYYY-MM-DD - Traffic Ticket (Comune di Pienza).pdf for parking/traffic violations.
• Travelers Auto Insurance: C:\Users\basua\Dropbox\Documents\Car\Travelers\
  • Naming: YYYY-MM-DD - Premium payment {YEAR}.pdf or YYYY-MM-DD - Billing Notice.pdf.

Rule 11: Taxes

• Destination: C:\Users\basua\Dropbox\Money\Tax\Abhi\YA{YEAR}\Documents\
• Naming: Follow precedent: {Owner} - {Entity} - {Form/Type}.pdf (e.g., Abhi - Fidelity (HSA) - 5498-SA.pdf).

Rule 12: Travel

• Destination: C:\Users\basua\Dropbox\Travel\{YYYY-MM - Destination}\
• Naming: YYYY-MM-DD - Description (Details).pdf.
• Deduplication: Always check if a flight confirmation is an update to an existing booking.

Rule 13: Software Installers

• Destination: C:\Users\basua\Dropbox\Software\To Install\
• Naming: Keep original installer name (e.g. Antigravity-x64.exe).

Rule 14: Fog City Advisors

• Destination: C:\Users\basua\Dropbox\Money\Fog City Advisors\
• Naming: YYYY-MM-DD - Invoice {Number}.pdf or YYYY-MM-DD - Payment receipt.pdf for advisory fees.