@waoooo/claude-skills 1.0.0

package/skills/worktree-manager/scripts/status.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# status.sh - Show status of all managed worktrees globally
+#
+# Usage: ./status.sh [--project <name>]
+#
+# Options:
+#   --project <name>   Filter to show only worktrees for specific project
+#
+# Examples:
+#   ./status.sh                              # All worktrees
+#   ./status.sh --project obsidian-ai-agent  # Only this project
+
+set -e
+
+PROJECT_FILTER=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --project)
+            PROJECT_FILTER="$2"
+            shift 2
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            echo "Usage: $0 [--project <name>]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+REGISTRY="${HOME}/.claude/worktree-registry.json"
+
+# Check if registry exists
+if [ ! -f "$REGISTRY" ]; then
+    echo "No worktree registry found at: $REGISTRY"
+    echo ""
+    echo "No worktrees are being tracked yet."
+    exit 0
+fi
+
+# Check if jq is available
+if ! command -v jq &> /dev/null; then
+    echo "Error: jq is required but not installed"
+    echo "Install with: brew install jq"
+    exit 1
+fi
+
+echo "═══════════════════════════════════════════════════════════════════════════════"
+echo "                        GLOBAL WORKTREE STATUS"
+if [ -n "$PROJECT_FILTER" ]; then
+    echo "                        (filtered: $PROJECT_FILTER)"
+fi
+echo "═══════════════════════════════════════════════════════════════════════════════"
+echo ""
+
+# Get worktrees, optionally filtered
+if [ -n "$PROJECT_FILTER" ]; then
+    WORKTREES=$(jq -c ".worktrees[] | select(.project == \"$PROJECT_FILTER\")" "$REGISTRY" 2>/dev/null || echo "")
+else
+    WORKTREES=$(jq -c '.worktrees[]' "$REGISTRY" 2>/dev/null || echo "")
+fi
+
+if [ -z "$WORKTREES" ]; then
+    if [ -n "$PROJECT_FILTER" ]; then
+        echo "No worktrees found for project: $PROJECT_FILTER"
+    else
+        echo "No worktrees registered."
+    fi
+    echo ""
+
+    # Show port pool status
+    echo "Port Pool:"
+    ALLOCATED=$(jq -r '.portPool.allocated | length' "$REGISTRY" 2>/dev/null || echo "0")
+    START=$(jq -r '.portPool.start // 8100' "$REGISTRY")
+    END=$(jq -r '.portPool.end // 8199' "$REGISTRY")
+    TOTAL=$((END - START + 1))
+    echo "  Allocated: $ALLOCATED / $TOTAL"
+    exit 0
+fi
+
+# Print header
+printf "%-25s %-20s %-12s %-8s %-10s %s\n" "PROJECT" "BRANCH" "PORTS" "PR" "STATUS" "TASK"
+printf "%-25s %-20s %-12s %-8s %-10s %s\n" "─────────────────────────" "────────────────────" "────────────" "────────" "──────────" "──────────────────────"
+
+# Process each worktree
+echo "$WORKTREES" | while read -r wt; do
+    PROJECT=$(echo "$wt" | jq -r '.project')
+    BRANCH=$(echo "$wt" | jq -r '.branch')
+    PORTS=$(echo "$wt" | jq -r '.ports | join(",")')
+    TASK=$(echo "$wt" | jq -r 'if .task == null then "-" else .task end')
+    PR=$(echo "$wt" | jq -r 'if .prNumber == null then "-" else .prNumber end')
+    STATUS=$(echo "$wt" | jq -r '.status // "active"')
+    WORKTREE_PATH=$(echo "$wt" | jq -r '.worktreePath')
+    REPO_PATH=$(echo "$wt" | jq -r '.repoPath')
+
+    # Truncate task if too long
+    if [ ${#TASK} -gt 25 ]; then
+        TASK="${TASK:0:22}..."
+    fi
+
+    # Truncate branch if too long
+    if [ ${#BRANCH} -gt 18 ]; then
+        BRANCH="${BRANCH:0:15}..."
+    fi
+
+    # Check if worktree directory exists
+    if [ ! -d "$WORKTREE_PATH" ]; then
+        STATUS="missing"
+    fi
+
+    # Check if original repo exists
+    if [ ! -d "$REPO_PATH" ]; then
+        STATUS="orphaned"
+    fi
+
+    # Check PR status if not set
+    if [ "$PR" = "-" ] && command -v gh &> /dev/null; then
+        PR_INFO=$(cd "$REPO_PATH" 2>/dev/null && gh pr list --head "$BRANCH" --json number,state --jq 'if length > 0 then .[0] | "\(.number):\(.state)" else "" end' 2>/dev/null || echo "")
+        if [ -n "$PR_INFO" ]; then
+            PR_NUM=$(echo "$PR_INFO" | cut -d':' -f1)
+            PR_STATE=$(echo "$PR_INFO" | cut -d':' -f2)
+            case "$PR_STATE" in
+                "OPEN") PR="#$PR_NUM" ;;
+                "MERGED") PR="#$PR_NUM ✓" ; STATUS="merged" ;;
+                "CLOSED") PR="#$PR_NUM ✗" ;;
+                *) PR="#$PR_NUM" ;;
+            esac
+        fi
+    else
+        PR="#$PR"
+    fi
+
+    # Check if any port is in use (indicates server running)
+    FIRST_PORT=$(echo "$PORTS" | cut -d',' -f1)
+    if lsof -i :"$FIRST_PORT" &>/dev/null; then
+        PORTS="${PORTS}*"
+    fi
+
+    printf "%-25s %-20s %-12s %-8s %-10s %s\n" "$PROJECT" "$BRANCH" "$PORTS" "$PR" "$STATUS" "$TASK"
+done
+
+echo ""
+echo "Legend: * = port in use, ✓ = PR merged, ✗ = PR closed"
+echo ""
+
+# Show port pool status
+echo "───────────────────────────────────────────────────────────────────────────────"
+echo "Port Pool:"
+ALLOCATED=$(jq -r '.portPool.allocated | length' "$REGISTRY")
+ALLOCATED_LIST=$(jq -r '.portPool.allocated | join(", ")' "$REGISTRY")
+START=$(jq -r '.portPool.start // 8100' "$REGISTRY")
+END=$(jq -r '.portPool.end // 8199' "$REGISTRY")
+TOTAL=$((END - START + 1))
+echo "  Range: $START-$END ($TOTAL total)"
+echo "  Allocated: $ALLOCATED ports"
+if [ "$ALLOCATED" -gt 0 ]; then
+    echo "  In use: $ALLOCATED_LIST"
+fi
+echo ""
+
+# Show worktree paths
+echo "───────────────────────────────────────────────────────────────────────────────"
+echo "Worktree Paths:"
+if [ -n "$PROJECT_FILTER" ]; then
+    jq -r ".worktrees[] | select(.project == \"$PROJECT_FILTER\") | \"  \\(.project)/\\(.branchSlug): \\(.worktreePath)\"" "$REGISTRY" 2>/dev/null
+else
+    jq -r '.worktrees[] | "  \(.project)/\(.branchSlug): \(.worktreePath)"' "$REGISTRY" 2>/dev/null
+fi

package/skills/worktree-manager/scripts/sync.sh

@@ -0,0 +1,168 @@
+#!/bin/bash
+# sync.sh - Reconcile registry with actual worktrees and PR status
+#
+# Usage: ./sync.sh [--quiet] [--fix]
+#
+# Options:
+#   --quiet  Only show issues, not OK entries
+#   --fix    Automatically fix issues (remove missing, update PR numbers)
+#
+# This script:
+# 1. Compares registry entries with actual git worktrees
+# 2. Checks PR status for each worktree branch
+# 3. Reports discrepancies
+# 4. Optionally fixes issues (with --fix)
+
+set -e
+
+REGISTRY="${HOME}/.claude/worktree-registry.json"
+QUIET=false
+FIX=false
+
+# Parse arguments
+for arg in "$@"; do
+    case $arg in
+        --quiet) QUIET=true ;;
+        --fix) FIX=true ;;
+    esac
+done
+
+# Check dependencies
+if ! command -v jq &> /dev/null; then
+    echo "Error: jq is required. Install with: brew install jq"
+    exit 1
+fi
+
+if ! command -v gh &> /dev/null; then
+    echo "Warning: gh (GitHub CLI) not found. PR status checks will be skipped."
+    HAS_GH=false
+else
+    HAS_GH=true
+fi
+
+# Check if registry exists
+if [ ! -f "$REGISTRY" ]; then
+    echo "Error: No registry found at: $REGISTRY"
+    exit 1
+fi
+
+echo "Syncing worktree registry..."
+echo "─────────────────────────────────────────────────────────"
+
+# Counters
+TOTAL=0
+MISSING=0
+MERGED=0
+ORPHANED=0
+UPDATED=0
+
+# Process each registry entry
+while IFS= read -r entry; do
+    [ -z "$entry" ] && continue
+
+    TOTAL=$((TOTAL + 1))
+    PROJECT=$(echo "$entry" | jq -r '.project')
+    BRANCH=$(echo "$entry" | jq -r '.branch')
+    WPATH=$(echo "$entry" | jq -r '.worktreePath')
+    CURRENT_PR=$(echo "$entry" | jq -r '.prNumber // "null"')
+    CURRENT_STATUS=$(echo "$entry" | jq -r '.status')
+
+    # Check if directory exists
+    if [ ! -d "$WPATH" ]; then
+        echo "❌ MISSING: $PROJECT / $BRANCH"
+        echo "   Path: $WPATH"
+        MISSING=$((MISSING + 1))
+
+        if [ "$FIX" = true ]; then
+            echo "   → Removing from registry..."
+            TMP=$(mktemp)
+            jq "del(.worktrees[] | select(.project == \"$PROJECT\" and .branch == \"$BRANCH\"))" "$REGISTRY" > "$TMP"
+            mv "$TMP" "$REGISTRY"
+            UPDATED=$((UPDATED + 1))
+        fi
+        continue
+    fi
+
+    # Check if it's a valid git worktree
+    if [ ! -f "$WPATH/.git" ] && [ ! -d "$WPATH/.git" ]; then
+        echo "⚠️  ORPHANED: $PROJECT / $BRANCH"
+        echo "   Path exists but not a git worktree"
+        ORPHANED=$((ORPHANED + 1))
+        continue
+    fi
+
+    # Check PR status
+    PR_NUM="null"
+    PR_STATE="NONE"
+
+    if [ "$HAS_GH" = true ]; then
+        PR_INFO=$(gh pr list --head "$BRANCH" --state all --json number,state --limit 1 2>/dev/null || echo "[]")
+        if [ "$PR_INFO" != "[]" ] && [ -n "$PR_INFO" ]; then
+            PR_NUM=$(echo "$PR_INFO" | jq -r '.[0].number // "null"')
+            PR_STATE=$(echo "$PR_INFO" | jq -r '.[0].state // "NONE"')
+        fi
+    fi
+
+    # Determine new status
+    NEW_STATUS="$CURRENT_STATUS"
+    if [ "$PR_STATE" = "MERGED" ]; then
+        NEW_STATUS="merged"
+        echo "✅ MERGED: $PROJECT / $BRANCH (PR #$PR_NUM)"
+        MERGED=$((MERGED + 1))
+    elif [ "$PR_STATE" = "OPEN" ]; then
+        NEW_STATUS="active"
+        if [ "$QUIET" = false ]; then
+            echo "🟢 ACTIVE: $PROJECT / $BRANCH (PR #$PR_NUM open)"
+        fi
+    elif [ "$PR_STATE" = "CLOSED" ]; then
+        NEW_STATUS="closed"
+        echo "🟡 CLOSED: $PROJECT / $BRANCH (PR #$PR_NUM closed without merge)"
+    else
+        if [ "$QUIET" = false ]; then
+            echo "🔵 NO PR: $PROJECT / $BRANCH"
+        fi
+    fi
+
+    # Update registry if needed
+    if [ "$FIX" = true ]; then
+        NEEDS_UPDATE=false
+
+        # Update prNumber if changed
+        if [ "$PR_NUM" != "null" ] && [ "$PR_NUM" != "$CURRENT_PR" ]; then
+            NEEDS_UPDATE=true
+        fi
+
+        # Update status if changed
+        if [ "$NEW_STATUS" != "$CURRENT_STATUS" ]; then
+            NEEDS_UPDATE=true
+        fi
+
+        if [ "$NEEDS_UPDATE" = true ]; then
+            TMP=$(mktemp)
+            if [ "$PR_NUM" != "null" ]; then
+                jq "(.worktrees[] | select(.project == \"$PROJECT\" and .branch == \"$BRANCH\")) |= . + {prNumber: $PR_NUM, status: \"$NEW_STATUS\"}" "$REGISTRY" > "$TMP"
+            else
+                jq "(.worktrees[] | select(.project == \"$PROJECT\" and .branch == \"$BRANCH\")).status = \"$NEW_STATUS\"" "$REGISTRY" > "$TMP"
+            fi
+            mv "$TMP" "$REGISTRY"
+            UPDATED=$((UPDATED + 1))
+            echo "   → Updated registry (PR: $PR_NUM, status: $NEW_STATUS)"
+        fi
+    fi
+
+done < <(jq -c '.worktrees[]' "$REGISTRY" 2>/dev/null)
+
+echo "─────────────────────────────────────────────────────────"
+echo "Summary:"
+echo "  Total entries: $TOTAL"
+echo "  Missing: $MISSING"
+echo "  Merged PRs: $MERGED"
+echo "  Orphaned: $ORPHANED"
+if [ "$FIX" = true ]; then
+    echo "  Updated: $UPDATED"
+fi
+
+if [ $MERGED -gt 0 ]; then
+    echo ""
+    echo "💡 Tip: Run 'cleanup.sh --merged' to remove merged worktrees"
+fi

package/skills/worktree-manager/templates/worktree.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Optional project-specific configuration for worktree-manager. Place at .claude/worktree.json in your project root.",
+
+  "ports": {
+    "count": 2,
+    "services": ["api", "frontend"]
+  },
+
+  "install": "uv sync",
+
+  "validate": {
+    "start": "PORT={{PORT}} docker-compose up -d",
+    "healthCheck": "curl -sf http://localhost:{{PORT}}/health",
+    "healthCheckTimeout": 30,
+    "stop": "docker-compose down"
+  },
+
+  "copyDirs": [".agents", ".env.example"],
+
+  "preBranch": null,
+  "postCreate": null
+}

package/skills/xlsx/LICENSE.txt

@@ -0,0 +1,30 @@
+© 2025 Anthropic, PBC. All rights reserved.
+
+LICENSE: Use of these materials (including all code, prompts, assets, files,
+and other components of this Skill) is governed by your agreement with
+Anthropic regarding use of Anthropic's services. If no separate agreement
+exists, use is governed by Anthropic's Consumer Terms of Service or
+Commercial Terms of Service, as applicable:
+https://www.anthropic.com/legal/consumer-terms
+https://www.anthropic.com/legal/commercial-terms
+Your applicable agreement is referred to as the "Agreement." "Services" are
+as defined in the Agreement.
+
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the
+contrary, users may not:
+
+- Extract these materials from the Services or retain copies of these
+  materials outside the Services
+- Reproduce or copy these materials, except for temporary copies created
+  automatically during authorized use of the Services
+- Create derivative works based on these materials
+- Distribute, sublicense, or transfer these materials to any third party
+- Make, offer to sell, sell, or import any inventions embodied in these
+  materials
+- Reverse engineer, decompile, or disassemble these materials
+
+The receipt, viewing, or possession of these materials does not convey or
+imply any license or right beyond those expressly granted above.
+
+Anthropic retains all right, title, and interest in these materials,
+including all copyrights, patents, and other intellectual property rights.

package/skills/xlsx/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: xlsx
+description: "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas"
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# Requirements for Outputs
+
+## All Excel files
+
+### Zero Formula Errors
+- Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)
+
+### Preserve Existing Templates (when updating templates)
+- Study and EXACTLY match existing format, style, and conventions when modifying files
+- Never impose standardized formatting on files with established patterns
+- Existing template conventions ALWAYS override these guidelines
+
+## Financial models
+
+### Color Coding Standards
+Unless otherwise stated by the user or existing template
+
+#### Industry-Standard Color Conventions
+- **Blue text (RGB: 0,0,255)**: Hardcoded inputs, and numbers users will change for scenarios
+- **Black text (RGB: 0,0,0)**: ALL formulas and calculations
+- **Green text (RGB: 0,128,0)**: Links pulling from other worksheets within same workbook
+- **Red text (RGB: 255,0,0)**: External links to other files
+- **Yellow background (RGB: 255,255,0)**: Key assumptions needing attention or cells that need to be updated
+
+### Number Formatting Standards
+
+#### Required Format Rules
+- **Years**: Format as text strings (e.g., "2024" not "2,024")
+- **Currency**: Use $#,##0 format; ALWAYS specify units in headers ("Revenue ($mm)")
+- **Zeros**: Use number formatting to make all zeros "-", including percentages (e.g., "$#,##0;($#,##0);-")
+- **Percentages**: Default to 0.0% format (one decimal)
+- **Multiples**: Format as 0.0x for valuation multiples (EV/EBITDA, P/E)
+- **Negative numbers**: Use parentheses (123) not minus -123
+
+### Formula Construction Rules
+
+#### Assumptions Placement
+- Place ALL assumptions (growth rates, margins, multiples, etc.) in separate assumption cells
+- Use cell references instead of hardcoded values in formulas
+- Example: Use =B5*(1+$B$6) instead of =B5*1.05
+
+#### Formula Error Prevention
+- Verify all cell references are correct
+- Check for off-by-one errors in ranges
+- Ensure consistent formulas across all projection periods
+- Test with edge cases (zero values, negative numbers)
+- Verify no unintended circular references
+
+#### Documentation Requirements for Hardcodes
+- Comment or in cells beside (if end of table). Format: "Source: [System/Document], [Date], [Specific Reference], [URL if applicable]"
+- Examples:
+  - "Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]"
+  - "Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]"
+  - "Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity"
+  - "Source: FactSet, 8/20/2025, Consensus Estimates Screen"
+
+# XLSX creation, editing, and analysis
+
+## Overview
+
+A user may ask you to create, edit, or analyze the contents of an .xlsx file. You have different tools and workflows available for different tasks.
+
+## Important Requirements
+
+**LibreOffice Required for Formula Recalculation**: You can assume LibreOffice is installed for recalculating formula values using the `recalc.py` script. The script automatically configures LibreOffice on first run
+
+## Reading and analyzing data
+
+### Data analysis with pandas
+For data analysis, visualization, and basic operations, use **pandas** which provides powerful data manipulation capabilities:
+
+```python
+import pandas as pd
+
+# Read Excel
+df = pd.read_excel('file.xlsx')  # Default: first sheet
+all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict
+
+# Analyze
+df.head()      # Preview data
+df.info()      # Column info
+df.describe()  # Statistics
+
+# Write Excel
+df.to_excel('output.xlsx', index=False)
+```
+
+## Excel File Workflows
+
+## CRITICAL: Use Formulas, Not Hardcoded Values
+
+**Always use Excel formulas instead of calculating values in Python and hardcoding them.** This ensures the spreadsheet remains dynamic and updateable.
+
+### ❌ WRONG - Hardcoding Calculated Values
+```python
+# Bad: Calculating in Python and hardcoding result
+total = df['Sales'].sum()
+sheet['B10'] = total  # Hardcodes 5000
+
+# Bad: Computing growth rate in Python
+growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
+sheet['C5'] = growth  # Hardcodes 0.15
+
+# Bad: Python calculation for average
+avg = sum(values) / len(values)
+sheet['D20'] = avg  # Hardcodes 42.5
+```
+
+### ✅ CORRECT - Using Excel Formulas
+```python
+# Good: Let Excel calculate the sum
+sheet['B10'] = '=SUM(B2:B9)'
+
+# Good: Growth rate as Excel formula
+sheet['C5'] = '=(C4-C2)/C2'
+
+# Good: Average using Excel function
+sheet['D20'] = '=AVERAGE(D2:D19)'
+```
+
+This applies to ALL calculations - totals, percentages, ratios, differences, etc. The spreadsheet should be able to recalculate when source data changes.
+
+## Common Workflow
+1. **Choose tool**: pandas for data, openpyxl for formulas/formatting
+2. **Create/Load**: Create new workbook or load existing file
+3. **Modify**: Add/edit data, formulas, and formatting
+4. **Save**: Write to file
+5. **Recalculate formulas (MANDATORY IF USING FORMULAS)**: Use the recalc.py script
+   ```bash
+   python recalc.py output.xlsx
+   ```
+6. **Verify and fix any errors**: 
+   - The script returns JSON with error details
+   - If `status` is `errors_found`, check `error_summary` for specific error types and locations
+   - Fix the identified errors and recalculate again
+   - Common errors to fix:
+     - `#REF!`: Invalid cell references
+     - `#DIV/0!`: Division by zero
+     - `#VALUE!`: Wrong data type in formula
+     - `#NAME?`: Unrecognized formula name
+
+### Creating new Excel files
+
+```python
+# Using openpyxl for formulas and formatting
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment
+
+wb = Workbook()
+sheet = wb.active
+
+# Add data
+sheet['A1'] = 'Hello'
+sheet['B1'] = 'World'
+sheet.append(['Row', 'of', 'data'])
+
+# Add formula
+sheet['B2'] = '=SUM(A1:A10)'
+
+# Formatting
+sheet['A1'].font = Font(bold=True, color='FF0000')
+sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
+sheet['A1'].alignment = Alignment(horizontal='center')
+
+# Column width
+sheet.column_dimensions['A'].width = 20
+
+wb.save('output.xlsx')
+```
+
+### Editing existing Excel files
+
+```python
+# Using openpyxl to preserve formulas and formatting
+from openpyxl import load_workbook
+
+# Load existing file
+wb = load_workbook('existing.xlsx')
+sheet = wb.active  # or wb['SheetName'] for specific sheet
+
+# Working with multiple sheets
+for sheet_name in wb.sheetnames:
+    sheet = wb[sheet_name]
+    print(f"Sheet: {sheet_name}")
+
+# Modify cells
+sheet['A1'] = 'New Value'
+sheet.insert_rows(2)  # Insert row at position 2
+sheet.delete_cols(3)  # Delete column 3
+
+# Add new sheet
+new_sheet = wb.create_sheet('NewSheet')
+new_sheet['A1'] = 'Data'
+
+wb.save('modified.xlsx')
+```
+
+## Recalculating formulas
+
+Excel files created or modified by openpyxl contain formulas as strings but not calculated values. Use the provided `recalc.py` script to recalculate formulas:
+
+```bash
+python recalc.py <excel_file> [timeout_seconds]
+```
+
+Example:
+```bash
+python recalc.py output.xlsx 30
+```
+
+The script:
+- Automatically sets up LibreOffice macro on first run
+- Recalculates all formulas in all sheets
+- Scans ALL cells for Excel errors (#REF!, #DIV/0!, etc.)
+- Returns JSON with detailed error locations and counts
+- Works on both Linux and macOS
+
+## Formula Verification Checklist
+
+Quick checks to ensure formulas work correctly:
+
+### Essential Verification
+- [ ] **Test 2-3 sample references**: Verify they pull correct values before building full model
+- [ ] **Column mapping**: Confirm Excel columns match (e.g., column 64 = BL, not BK)
+- [ ] **Row offset**: Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)
+
+### Common Pitfalls
+- [ ] **NaN handling**: Check for null values with `pd.notna()`
+- [ ] **Far-right columns**: FY data often in columns 50+ 
+- [ ] **Multiple matches**: Search all occurrences, not just first
+- [ ] **Division by zero**: Check denominators before using `/` in formulas (#DIV/0!)
+- [ ] **Wrong references**: Verify all cell references point to intended cells (#REF!)
+- [ ] **Cross-sheet references**: Use correct format (Sheet1!A1) for linking sheets
+
+### Formula Testing Strategy
+- [ ] **Start small**: Test formulas on 2-3 cells before applying broadly
+- [ ] **Verify dependencies**: Check all cells referenced in formulas exist
+- [ ] **Test edge cases**: Include zero, negative, and very large values
+
+### Interpreting recalc.py Output
+The script returns JSON with error details:
+```json
+{
+  "status": "success",           // or "errors_found"
+  "total_errors": 0,              // Total error count
+  "total_formulas": 42,           // Number of formulas in file
+  "error_summary": {              // Only present if errors found
+    "#REF!": {
+      "count": 2,
+      "locations": ["Sheet1!B5", "Sheet1!C10"]
+    }
+  }
+}
+```
+
+## Best Practices
+
+### Library Selection
+- **pandas**: Best for data analysis, bulk operations, and simple data export
+- **openpyxl**: Best for complex formatting, formulas, and Excel-specific features
+
+### Working with openpyxl
+- Cell indices are 1-based (row=1, column=1 refers to cell A1)
+- Use `data_only=True` to read calculated values: `load_workbook('file.xlsx', data_only=True)`
+- **Warning**: If opened with `data_only=True` and saved, formulas are replaced with values and permanently lost
+- For large files: Use `read_only=True` for reading or `write_only=True` for writing
+- Formulas are preserved but not evaluated - use recalc.py to update values
+
+### Working with pandas
+- Specify data types to avoid inference issues: `pd.read_excel('file.xlsx', dtype={'id': str})`
+- For large files, read specific columns: `pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])`
+- Handle dates properly: `pd.read_excel('file.xlsx', parse_dates=['date_column'])`
+
+## Code Style Guidelines
+**IMPORTANT**: When generating Python code for Excel operations:
+- Write minimal, concise Python code without unnecessary comments
+- Avoid verbose variable names and redundant operations
+- Avoid unnecessary print statements
+
+**For Excel files themselves**:
+- Add comments to cells with complex formulas or important assumptions
+- Document data sources for hardcoded values
+- Include notes for key calculations and model sections