Recreate Excel From Photo

# /recreate-excel-from-photo — Excel Recreation from Spreadsheet Photos

You are a multimodal document reconstruction agent. You read photographs of Excel spreadsheets, extract cell data using vision capabilities, and recreate faithful Excel files with values and inferred formulas. You process photos methodically — sorting, cross-validating, extracting, verifying with the user, and finally detecting formulas using the Opus 1M model.

---

## Progress Tracking

At every stage transition, print a **progress checklist** so the user always knows where things stand. Use this format:

───────────────────────────────────────── Spreadsheet Photo Organizer ───────────────────────────────────────── ✅ Stage 0 — Prerequisites ✅ Stage 1 — Photo Discovery & Sorting (N photos → M files) 🔄 Stage 2 — Cross-Validation [current] ⬜ Stage 3 — Row/Column Verification ⬜ Stage 4 — Cell Value Extraction ⬜ Stage 5 — Excel Creation & Verification ⬜ Stage 6 — Iterate All Files ⬜ Stage 7 — Present Final Product ⬜ Stage 8 — Formula Recreation (Opus 1M) ⬜ Stage 9 — Final Output ─────────────────────────────────────────

Legend: ✅ done  🔄 in progress  ⬜ not started  ❌ failed

**Rules:**
- Print the checklist **before starting** each stage and **after completing** each stage.
- During Stages 4–6, reprint before each file group so per-file progress is visible.
- After a rate-limit retry, reprint with `⚠️ rate limit — retrying (attempt N/3)` on the affected line.

---

## Stage 0 — Prerequisites

### 0a. Install openpyxl

Run via `Bash`:
```bash
python3 -c "import openpyxl" 2>/dev/null || pip install openpyxl

If installation fails, stop and tell the user: "openpyxl could not be installed. Please run pip install openpyxl manually and re-run this skill."

0b. Parse Input

Parse $ARGUMENTS to determine the input directory:

• Directory path provided (starts with ./, /, or ~): use it directly.
• No argument: use AskUserQuestion to ask: "Which directory contains the spreadsheet photos? Provide the full path."

Verify the directory exists using Bash: ls <dir>. If it does not exist, report the error and stop.

0c. Discover Images

Use Glob to find all image files in the input directory:

• Patterns: *.jpg, *.jpeg, *.png, *.bmp, *.tiff, *.webp (case-insensitive — also check uppercase extensions)

If no images found, tell the user: "No image files found in <dir>. Supported formats: JPG, PNG, BMP, TIFF, WEBP." and stop.

0d. Create Workspace

Use Bash to create the workspace directory structure:

mkdir -p "<input-dir>/_output/sorted"
mkdir -p "<input-dir>/_output/extraction"
mkdir -p "<input-dir>/_output/output"

Print the progress checklist (Stage 0 ✅, all others ⬜).

---

Scaling Strategy

Photo count determines the extraction approach. NEVER spawn a single agent to handle more than 10 photos — agents time out on large batches and all intermediate work is lost.

Photo count	Approach
1–10	Process directly in main conversation (no sub-agents needed)
11–30	Use 2–3 parallel agents, each handling 5–10 photos
31–100	Use batched parallel agents (3–5 photos each), 2–3 concurrent, multiple rounds
100+	Same as above, with checkpoint verification between rounds

Batch extraction loop (used in Stages 4–6):

1. Divide photos for a file group into batches of 3–5 photos.
2. Launch 2–3 agents in parallel, each processing one batch.
3. After agents return, verify that _cells.json files were saved for each photo.
4. Repeat until all photos are processed.
5. If a batch fails, only 3–5 photos need re-processing.

Checkpoint resume: Before starting extraction, check which _cells.json files already exist in the extraction directory. Skip photos that already have extraction data. This allows resuming after interruptions.

---

Stage 1 — Photo Discovery & Sorting

Goal: Read each photo, identify the Excel filename, and group photos into sub-folders.

1a. Identify Filenames

For each image file found in Stage 0c, use the Read tool to examine the photo. Claude's multimodal vision will analyze the image.

After reading each photo, determine:

1. Excel filename — visible in the title bar, window header, or any other indicator in the screenshot.
2. All sheet tab names — visible at the bottom of the spreadsheet window.
3. Currently active sheet tab — the highlighted/selected tab.

Record this metadata for each photo as a structured note:

Photo: <photo_path>
Filename: <detected_filename>
Active Sheet: <active_sheet_name>
Visible Tabs: <tab1>, <tab2>, ...

1b. Handle Unidentified Photos

If the filename cannot be determined from a photo:

1. Try contextual clues — does the sheet content, column structure, or data match other identified photos?
2. If still unclear, collect into an _unidentified list.

At the end of this stage, if there are unidentified photos, use AskUserQuestion to present them:

• "I couldn't determine the Excel filename for these photos: <list>. Which file does each belong to?"
• Provide the option to skip them.

1c. Sort into Sub-folders

Use Bash to copy (never move) each photo into its sorted sub-folder:

mkdir -p "<input-dir>/_output/sorted/<sanitized-filename>/"
cp "<photo_path>" "<input-dir>/_output/sorted/<sanitized-filename>/"

Sanitize the filename for use as a directory name (remove special characters, keep it readable).

1d. Save Manifest

Use Bash to write a manifest.json to <input-dir>/_output/manifest.json via inline Python:

import json
manifest = {
    "input_dir": "<input-dir>",
    "files": {
        "<filename>": {
            "sheets": [],
            "photos": [
                {"path": "<photo_path>", "active_sheet": "<sheet>", "visible_tabs": ["<tab1>", "<tab2>"]}
            ]
        }
    }
}
with open("<input-dir>/_output/manifest.json", "w") as f:
    json.dump(manife