@heylemon/lemonade 0.1.6 → 0.1.7

package/skills/xlsx/SKILL.md

@@ -1,23 +1,511 @@
 ---
-name: xlsx
-description: "Create professional spreadsheets, dashboards, and financial models in .xlsx with deterministic scripts and formula validation."
-license: Proprietary. LICENSE.txt has complete terms
+name: pro-sheets
+description: "Create professional, formatted spreadsheets — dashboards, data tables, financial models, trackers, and reports. Use this skill whenever the user wants to create or edit a spreadsheet, Excel file, tracker, financial model, budget, forecast, data table, or dashboard. Trigger on 'spreadsheet', 'xlsx', 'excel', 'workbook', 'financial model', 'budget', 'forecast', 'tracker', 'dashboard'."
 ---
 
-# Pro Sheets for XLSX
+# Pro Sheets — Professional Excel Development
 
-Use structured JSON specs and the script pair below:
+Build polished, formula-driven Excel workbooks using openpyxl. The AI writes Python code directly each time—no wrapper scripts—tailoring each implementation to the user's request. All formulas are calculated via LibreOffice, ensuring accuracy.
+
+## Key Architecture
+
+- **Direct openpyxl coding**: Write formulas inline, customize formatting, control layout without abstraction layers
+- **Mandatory LibreOffice recalculation**: All formulas evaluated before delivering the file
+- **Industry-standard financial modeling**: Color coding, number formatting, documentation standards
+- **pandas for data prep**: Load, analyze, reshape before building the spreadsheet
+
+## Requirements for Outputs
+
+Every Excel file must meet these baseline standards:
+
+### All Spreadsheets
+- **Font**: Arial or similar professional font, consistent throughout
+- **Formula integrity**: Zero formula errors—no #REF!, #DIV/0!, #VALUE!, #N/A, #NAME?, #NULL!, #NUM!
+- **Template preservation**: When editing existing files, maintain their structure and style
+
+### Financial Models (strict standards)
+
+**Color Coding** (Excel RGB values):
+- **Blue text (0,0,255)**: Hardcoded input values—numbers the user will change for scenarios
+- **Black text (0,0,0)**: Formula cells (calculations, SUM, cross-references)
+- **Green text (0,128,0)**: Cross-sheet references (formulas that link between sheets)
+- **Red text (255,0,0)**: External references (data pulled from outside sources)
+- **Yellow background**: Key assumptions—the 5-10 drivers that change model outputs most
+
+**Number Formatting**:
+- Currency: `$#,##0` or `$#,##0,"K"` for thousands (e.g., $45K)
+- Percentages: `0.0%` (e.g., 15.2%)
+- Multiples/ratios: `0.0x` (e.g., 3.2x)
+- Years: Text format (2026, not 2,026)
+- Zero values: Display as "–" not 0
+- Negative numbers: Parentheses `($#,##0)` not minus sign
+
+**Formula Rules**:
+- Assumptions always in separate cells, never hardcoded in formulas
+  - ❌ Bad: `=Revenue * 0.15`  (hardcoded margin)
+  - ✅ Good: `=Revenue * B5` where B5 contains 0.15 with cell comment "Gross Margin"
+- Cell references, not hardcoded values: formulas link cells, not embed numbers
+- Document data sources: If a cell contains a hardcoded number, add a comment explaining its origin
+
+**Documentation**:
+- Complex formulas: Add Excel comments explaining logic
+- Data sources: Cite external sources for hardcoded values
+- Assumptions sheet: Keep all key inputs in one place, clearly labeled
+
+## Critical: Use Formulas, Not Hardcoded Values
+
+This is the core difference between dynamic spreadsheets and static reports. The spreadsheet must recalculate automatically when users change inputs.
+
+### Wrong Approach
+```python
+import pandas as pd
+df = pd.read_csv('sales.csv')
+total = df['Sales'].sum()
+sheet['B10'] = total  # ❌ Hardcoded—won't update if sales change
+```
+
+### Correct Approach
+```python
+# Load data, analyze it to understand structure
+df = pd.read_excel('sales.csv')
+print(df.shape, df.columns)
+
+# But put the data in the spreadsheet
+for idx, row in df.iterrows():
+    sheet[f'A{idx+2}'] = row['Product']
+    sheet[f'B{idx+2}'] = row['Sales']
+
+# Use formulas for calculations
+sheet['B10'] = '=SUM(B2:B9)'  # ✅ Dynamic—updates when sales change
+```
+
+## Reading and Analyzing Data
+
+Use pandas to understand data before building the spreadsheet:
+
+```python
+import pandas as pd
+
+# Single sheet
+df = pd.read_excel('file.xlsx')
+
+# All sheets
+all_sheets = pd.read_excel('file.xlsx', sheet_name=None)
+for sheet_name, data in all_sheets.items():
+    print(f"{sheet_name}: {data.shape}")
+
+# Specify dtypes and ranges
+df = pd.read_excel('file.xlsx', sheet_name='Sales',
+                   dtype={'Year': str, 'Amount': float},
+                   usecols=['Product', 'Amount', 'Date'])
+```
+
+## Common Workflow
+
+1. **Choose the tool**: pandas for data analysis, openpyxl for formulas and formatting
+2. **Load/create workbook**: `from openpyxl import Workbook` or `load_workbook()`
+3. **Modify data, formulas, formatting**: Write cells with openpyxl
+4. **Save**: `wb.save('output.xlsx')`
+5. **Recalculate formulas** (MANDATORY): `python scripts/recalc.py output.xlsx`
+6. **Verify and fix**: Check recalc output for errors
+
+## Dashboard Design
+
+Dashboards are high-visibility outputs. They must look polished when opened — not cramped, clipped, or hard to read.
+
+### KPI Cards That Breathe
+
+The #1 mistake: cramming large KPI values into tiny merged cells. Excel clips text that doesn't fit, making stats invisible.
+
+**Rules for KPI cards:**
+- **Column width ≥ 18** per card (not 10-14). If merging 2 columns, each should be ≥ 18
+- **Row height for large fonts**: `ws.row_dimensions[row].height = font_size * 2.2` minimum
+- **Explicit row heights** for every KPI row (value, label, change indicator)
+- **Spacer rows** (height 8-12) above and below the KPI band to separate visually
+- **Max 4 KPIs per row** — more than that and they crowd. Use a second row if needed
+
+**KPI card pattern** (2 merged columns per card, no gutter columns — keeps table alignment simple):
+```python
+# 4 KPIs = 8 columns (2 per card). Tables below use columns A-D within the same grid.
+kpis = [
+    ("12,400", "Current MAU", "+34% QoQ", True),
+    ("$48K", "MRR", "+52% QoQ", True),
+    ("62", "NPS", "+8 pts", True),
+    ("$42", "CAC", "↓ from $58", True),
+]
+
+kpi_start = 3
+ws.row_dimensions[kpi_start - 1].height = 10  # Spacer above
+
+for i, (value, label, change, is_positive) in enumerate(kpis):
+    col = i * 2 + 1  # 2 columns per card, no gutter
+
+    # Merge 2 columns for each row
+    for dr in range(3):
+        ws.merge_cells(start_row=kpi_start + dr, start_column=col,
+                       end_row=kpi_start + dr, end_column=col + 1)
+
+    # Value — large, bold, colored
+    ws.cell(kpi_start, col, value).font = Font(name="Arial", size=22, bold=True, color="2E86AB")
+    ws.cell(kpi_start, col).alignment = Alignment(horizontal="center", vertical="center")
+
+    # Label — muted
+    ws.cell(kpi_start + 1, col, label).font = Font(name="Arial", size=9, color="7F8C8D")
+    ws.cell(kpi_start + 1, col).alignment = Alignment(horizontal="center")
+
+    # Change — green/red
+    color = "27AE60" if is_positive else "E74C3C"
+    ws.cell(kpi_start + 2, col, change).font = Font(name="Arial", size=9, bold=True, color=color)
+    ws.cell(kpi_start + 2, col).alignment = Alignment(horizontal="center")
+
+    # Card background + border
+    card_fill = PatternFill("solid", fgColor="FFF8E1")
+    for dr in range(3):
+        for dc in range(2):
+            ws.cell(kpi_start + dr, col + dc).fill = card_fill
+            ws.cell(kpi_start + dr, col + dc).border = thin_border
+
+    # Column widths — 18 minimum per column in the card
+    ws.column_dimensions[get_column_letter(col)].width = 18
+    ws.column_dimensions[get_column_letter(col + 1)].width = 18
+
+# ROW HEIGHTS — the critical fix for merged cells
+ws.row_dimensions[kpi_start].height = 48       # Value row — must fit size-22 font
+ws.row_dimensions[kpi_start + 1].height = 20   # Label row
+ws.row_dimensions[kpi_start + 2].height = 20   # Change row
+
+# Spacer rows below KPIs before tables start
+ws.row_dimensions[kpi_start + 3].height = 12
+ws.row_dimensions[kpi_start + 4].height = 6
+```
+
+**Why no gutter columns:** Adding narrow spacer columns between KPI cards creates misalignment with the data tables below (which use columns A-D). Keep the column grid consistent — KPI cards and tables should share the same column structure where possible.
+
+**Common dashboard mistakes to avoid:**
+- Column width under 16 for KPI cards (text clips silently in merged cells)
+- No `row_dimensions[].height` set (Excel auto-height fails with merged cells — this is the #1 cause of hidden stats)
+- KPI cards touching the tables below (add spacer rows, height 10-16)
+- Gutter columns between cards that break table alignment below
+- Too many merged cells in data tables (breaks sorting and filtering)
+- Using merged cells for data tables at all — only use them for titles and KPI cards
+
+### Section Titles and Table Spacing
+- Section titles: 1 empty spacer row above (height 16-20), bold font size 13-14
+- Tables: Start on the row immediately after the header row, no gap
+- Between tables: 2 empty rows minimum (or 1 spacer row with height 24+)
+
+## Creating New Files
+
+Use openpyxl directly. Here's a typical workflow:
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment, numbers
+from openpyxl.utils import get_column_letter
+
+wb = Workbook()
+ws = wb.active
+ws.title = "Sales"
+
+# Headers with styling
+headers = ["Product", "Q1 Sales", "Q2 Sales", "Total"]
+for col, header in enumerate(headers, 1):
+    cell = ws.cell(1, col)
+    cell.value = header
+    cell.font = Font(bold=True, color="FFFFFF", name="Arial")
+    cell.fill = PatternFill(start_color="1B3A5C", end_color="1B3A5C", fill_type="solid")
+    cell.alignment = Alignment(horizontal="center")
+
+# Data rows
+products = [("Widget A", 10000, 12000), ("Widget B", 8000, 9500)]
+for row_idx, (product, q1, q2) in enumerate(products, 2):
+    ws.cell(row_idx, 1).value = product
+    ws.cell(row_idx, 2).value = q1
+    ws.cell(row_idx, 3).value = q2
+    # Formula for total
+    ws.cell(row_idx, 4).value = f"=B{row_idx}+C{row_idx}"
+    # Number formatting
+    ws.cell(row_idx, 2).number_format = "$#,##0"
+    ws.cell(row_idx, 3).number_format = "$#,##0"
+    ws.cell(row_idx, 4).number_format = "$#,##0"
+
+# Totals row
+total_row = len(products) + 2
+ws.cell(total_row, 1).value = "TOTAL"
+ws.cell(total_row, 2).value = f"=SUM(B2:B{total_row-1})"
+ws.cell(total_row, 3).value = f"=SUM(C2:C{total_row-1})"
+ws.cell(total_row, 4).value = f"=SUM(D2:D{total_row-1})"
+
+# Column widths
+ws.column_dimensions['A'].width = 15
+ws.column_dimensions['B'].width = 12
+ws.column_dimensions['C'].width = 12
+ws.column_dimensions['D'].width = 12
+
+# Freeze header
+ws.freeze_panes = "A2"
+
+# Auto-filter
+ws.auto_filter.ref = f"A1:D{total_row}"
+
+wb.save('output.xlsx')
+```
+
+### Common Formatting Tasks
+
+**Font colors for financial models**:
+```python
+cell = ws['B5']
+cell.font = Font(color="0000FF")  # Blue for inputs
+```
+
+**Cell number formats**:
+```python
+ws['B2'].number_format = '$#,##0'        # Currency
+ws['C3'].number_format = '0.0%'          # Percentage
+ws['D4'].number_format = '0.0x'          # Multiple
+ws['E5'].number_format = 'YYYY'          # Year as text
+```
+
+**Borders**:
+```python
+from openpyxl.styles import Border, Side
+
+thin_border = Border(
+    left=Side(style='thin'),
+    right=Side(style='thin'),
+    top=Side(style='thin'),
+    bottom=Side(style='thin')
+)
+ws['B2'].border = thin_border
+```
+
+**Merged cells** (use sparingly, never in data tables):
+```python
+ws.merge_cells('A1:D1')
+ws['A1'] = 'Q1 2026 Performance'
+```
+
+**Row heights for merged cells** (critical — Excel auto-height fails with merges):
+```python
+# ALWAYS set explicit row heights when using large fonts or merged cells
+ws.row_dimensions[1].height = 36  # Title row
+ws.row_dimensions[3].height = 52  # Large KPI values (size 20-26 font)
+ws.row_dimensions[4].height = 22  # KPI labels
+```
+
+## Editing Existing Files
+
+```python
+from openpyxl import load_workbook
+
+# Load without calculating (preserves formulas)
+wb = load_workbook('existing.xlsx')
+ws = wb['Sales']
+
+# Modify cells
+ws['B2'].value = 50000
+
+# Insert rows (shifts everything below)
+ws.insert_rows(5, 3)  # Insert 3 rows at row 5
+
+# Delete rows
+ws.delete_rows(5, 2)  # Delete 2 rows starting at row 5
+
+# Add new sheet
+new_sheet = wb.create_sheet('Assumptions', 0)  # Insert at position 0
+
+# Save
+wb.save('existing.xlsx')
+```
+
+### Critical Warning: data_only=True Destroys Formulas
+
+```python
+# ❌ WRONG: Loads calculated values, strips formulas
+wb = load_workbook('file.xlsx', data_only=True)
+
+# ✅ RIGHT: Preserves formulas for editing
+wb = load_workbook('file.xlsx', data_only=False)  # or just omit
+```
+
+## Formula Recalculation
+
+After creating or editing any file with formulas, **always recalculate**:
 
 ```bash
-pip install openpyxl --break-system-packages 2>/dev/null
-python scripts/create_xlsx.py spec.json output.xlsx
-python scripts/validate_xlsx.py output.xlsx
+python scripts/recalc.py output.xlsx [timeout_seconds]
+```
+
+### What It Does
+- Sets up LibreOffice macro (RecalculateAndSave) on first run
+- Runs soffice headless to open the file and recalculate all formulas
+- Scans all cells for Excel error values: #VALUE!, #DIV/0!, #REF!, #NAME?, #NULL!, #NUM!, #N/A
+- Returns JSON with status, error count, and locations
+
+### Output Format
+```json
+{
+  "status": "success",
+  "total_errors": 0,
+  "total_formulas": 145,
+  "error_summary": {},
+  "error_details": [],
+  "file": "output.xlsx"
+}
+```
+
+If errors exist:
+```json
+{
+  "status": "errors_found",
+  "total_errors": 2,
+  "error_summary": {
+    "#DIV/0!": 1,
+    "#REF!": 1
+  },
+  "error_details": [
+    {"cell": "C5", "error": "#DIV/0!", "sheet": "Sales"},
+    {"cell": "F12", "error": "#REF!", "sheet": "Assumptions"}
+  ]
+}
 ```
 
-Rules:
-- Always use formulas (never hardcode calculated values).
-- Keep headers clear with units.
-- Keep formatting consistent.
-- For financial models: blue inputs, black formulas, yellow assumptions.
+## Formula Verification Checklist
+
+### Essential Tests
+- **Cell references**: Verify all cell addresses are correct (B2, not B2:B2)
+- **Column mapping**: Ensure formula references match data layout
+- **Row offsets**: Check that formulas adjust correctly when rows are inserted/deleted
+- **Sheet references**: Confirm cross-sheet formulas use correct syntax: `='Sheet Name'!A1`
+
+### Common Pitfalls
+- **NaN in formulas**: If source data contains empty cells, wrap with IF: `=IF(ISBLANK(B2),0,B2*C2)`
+- **Far-right columns**: Column Z, AA, AB—verify Excel alphabet mapping
+- **Division by zero**: Always guard: `=IF(B2=0,0,A2/B2)`
+- **Wrong sheet references**: `=SUM(Data!B:B)` not `=SUM(Data.B:B)`
+- **Cross-sheet format mismatch**: If Formula sheet references Data sheet, ensure same row structure
+
+### Testing Strategy
+1. **Start small**: Create 5-row test version, verify formulas calculate
+2. **Verify dependencies**: If C = A + B, test that changing A updates C
+3. **Test edge cases**: Empty cells, zeros, negative numbers, very large numbers
+4. **Run recalc.py**: Always validate before delivering
+
+## Best Practices
+
+### Choosing Tools
+
+**Use pandas when**:
+- Loading CSV, Excel, database data
+- Data cleaning: pivots, filters, groupby
+- Analysis: aggregations, calculations on entire dataset
+- Output: single DataFrame to spreadsheet
+
+**Use openpyxl when**:
+- Building custom layouts (merged cells, KPI cards)
+- Complex formatting (fonts, colors, borders)
+- Formulas and dynamic calculations
+- Editing existing files
+- Multi-sheet workbooks with cross-references
+
+### openpyxl Tips
+
+**1-based indexing**: Row and column numbers start at 1
+```python
+ws.cell(1, 1)  # A1
+ws.cell(5, 3)  # C5
+ws['A1']       # Also A1
+```
+
+**Preserve formulas when loading**:
+```python
+wb = load_workbook('file.xlsx')  # Preserves formulas
+# NOT: load_workbook('file.xlsx', data_only=True)
+```
+
+**Large files**: Use read_only or write_only mode
+```python
+wb = load_workbook('huge.xlsx', read_only=True)  # For reading only
+ws = wb.active
+for row in ws.iter_rows():
+    # Process
+```
+
+**Iterating ranges**:
+```python
+# By row
+for row in ws.iter_rows(min_row=2, max_row=100, values_only=False):
+    for cell in row:
+        print(cell.value)
+
+# By column
+for col in ws.iter_cols(min_col=1, max_col=5):
+    for cell in col:
+        print(cell.value)
+```
+
+### pandas Tips
+
+**Specify data types** to avoid parsing errors:
+```python
+df = pd.read_excel('file.xlsx', dtype={'Year': str, 'Amount': float})
+```
+
+**Load specific columns** to reduce memory:
+```python
+df = pd.read_excel('file.xlsx', usecols=['Product', 'Sales', 'Date'])
+```
+
+**Parse dates**:
+```python
+df = pd.read_excel('file.xlsx', parse_dates=['Close Date'])
+```
+
+## Code Style Guidelines
+
+Write minimal, concise Python. Avoid unnecessary comments—the code should be clear. But DO add Excel cell comments for complex formulas.
+
+```python
+# Good: Clear variable names, no fluff
+df = pd.read_excel('sales.csv')
+for idx, row in df.iterrows():
+    ws[f'A{idx+2}'] = row['Product']
+    ws[f'B{idx+2}'] = row['Amount']
+
+# Bad: Excessive comments
+# Load the Excel file from disk
+df = pd.read_excel('sales.csv')  # Read the CSV
+# Loop through each row
+for idx, row in df.iterrows():  # Iterate rows
+    ws[f'A{idx+2}'] = row['Product']  # Set product name
+```
+
+**For complex formulas, add Excel comments**:
+```python
+# In Python, calculate but explain in the sheet
+ws['E5'].value = '=IF(D5=0,0,(C5-B5)/B5)'  # YoY growth
+ws['E5'].comment = Comment("YoY growth % = (Current - Prior) / Prior", author="Model")
+```
+
+## Financial Model Structure Example
+
+```
+Row 1:    [Metric]           [2024A]  [2025E]  [2026E]  [2027E]
+Row 2:    Revenue ($K)       [1000]   [1500]   [2100]   [2800]   <- Blue inputs
+Row 3:    Growth Rate        —        50%      40%      33%      <- Blue inputs, yellow bg
+Row 4:    COGS ($K)          [400]    [600]    [820]    [1090]   <- Formulas (black)
+Row 5:    Gross Margin %     40.0%    40.0%    39.0%    39.0%    <- Blue inputs, yellow bg
+Row 6:    OpEx ($K)          [300]    [350]    [420]    [500]    <- Blue inputs
+Row 7:    EBITDA ($K)        [300]    [550]    [860]    [1210]   <- Formulas (black)
+
+Formulas:
+C2 = B2 * (1 + C3)     [2024 * (1 + growth)]
+C4 = C2 * (1 - C5)     [Revenue * (1 - COGS margin)]
+C7 = C2 - C4 - C6      [Revenue - COGS - OpEx]
+```
 
-See `references/spec-format.md` for full JSON schema and examples.
+Cell colors:
+- B2, C3, D3, E3: Blue text (inputs)
+- C3, D3, E3: Yellow background (key assumptions)
+- C2, C4, C7: Black text (formulas)