spreadsheet-validated-exec

Validated Python Execution for Spreadsheet Tasks

Overview

This skill extends direct Python execution for spreadsheet operations by adding a mandatory data validation phase before any processing begins. This prevents wasted iterations on inaccessible data sources and provides clear error documentation when data cannot be accessed.

When to Use This Skill

Use validated direct run_shell with Python scripts for spreadsheet operations when:

• Reading or writing complex Excel files with multiple sheets
• Data sources have already been validated as accessible
• You have fallback sources identified in case of access failures
• Applying formulas, formatting, or data transformations
• Working with openpyxl, pandas, or similar libraries
• The operation involves multiple steps that could exceed agent step limits
• You need precise control over error handling and debugging
• Complex scripts benefit from file-based execution for better reliability

Why Validated Direct Execution?

Beyond standard shell_agent limitations, unvalidated data access causes:

• Wasted iterations attempting to process non-existent data
• Unclear error messages when source files are inaccessible
• No graceful degradation when primary sources fail
• Missing documentation of why data operations couldn't complete

Direct run_shell with Python validation is more reliable because it:

• Executes validation in a single step with no iteration limits
• Provides clearer, immediate error messages for access failures
• Handles complex operations without step constraints
• Gives full control over library imports and execution flow
• Writing scripts to .py files first avoids shell_agent parsing issues with heredocs
• Documents all access failures for troubleshooting and reporting

Phase 0: Data Source Validation (REQUIRED)

Before writing any spreadsheet processing code, verify your data sources are accessible:

Step 0.1: Verify Data Availability

import os
import requests
from pathlib import Path

# For local files
def verify_local_file(file_path):
    path = Path(file_path)
    if not path.exists():
        raise FileNotFoundError(f"Data file not found: {file_path}")
    if not path.is_file():
        raise ValueError(f"Path is not a file: {file_path}")
    if path.stat().st_size == 0:
        raise ValueError(f"Data file is empty: {file_path}")
    print(f"✓ Local file verified: {file_path} ({path.stat().st_size} bytes)")
    return True

# For remote URLs
def verify_remote_url(url, timeout=30):
    try:
        # Try HEAD request first (lighter than GET)
        response = requests.head(url, timeout=timeout, allow_redirects=True)
        if response.status_code == 405:  # HEAD not allowed, try GET
            response = requests.get(url, timeout=timeout, stream=True)
        response.raise_for_status()
        
        # Check content type if available
        content_type = response.headers.get('Content-Type', '')
        if 'text/html' in content_type and 'excel' not in url.lower():
            print(f"⚠ Warning: URL may return HTML, not data file")
        
        print(f"✓ Remote URL verified: {url} (Status: {response.status_code})")
        return True
    except requests.exceptions.SSLError as e:
        print(f"✗ SSL Error: {str(e)}")
        return False
    except requests.exceptions.ConnectionError as e:
        print(f"✗ Connection Error: {str(e)}")
        return False
    except requests.exceptions.Timeout as e:
        print(f"✗ Timeout Error: {str(e)}")
        return False
    except Exception as e:
        print(f"✗ Verification Failed: {str(e)}")
        return False