alleato-budget-import

---
name: alleato-budget-import
description: Use this skill when importing, reviewing, dry-running, or verifying legacy project-management budget Excel workbooks for Alleato projects, especially `.xlsx` files with a `Budget Code` column that should be loaded through `/Users/meganharrison/Documents/alleato-pm/scripts/import_legacy_budget.py`.
---

# Alleato Budget Import

## Purpose

Use the existing Alleato importer for legacy Procore-style budget exports. Do not invent a new import path unless the workbook does not fit the script contract.

Canonical repo:

`/Users/meganharrison/Documents/alleato-pm`

Canonical importer:

`scripts/import_legacy_budget.py`

## Workflow

1. Inspect the workbook before touching Supabase.
   - Confirm the first sheet has `Budget Code`.
   - Record row count excluding `Grand Total:`.
   - Record totals for `Original Budget`, `Budget Modifications`, `Contract Change Orders`, and `Revised Budget` when present.
   - Flag zero-original-budget rows with actuals, commitments, or projected costs as data caveats, not blockers.

2. Resolve the target project.
   - Use `--list-projects --project-query "<name fragment>"`.
   - If multiple projects match, do not guess. Use the exact project name/number or ask for confirmation.

3. Convert first.

```bash
python3 scripts/import_legacy_budget.py --input /path/to/budget.xlsx --convert-only
```

Expected output:

`output/spreadsheet/<workbook-stem>-import-ready.csv`

4. Dry-run before real import.

   Before trusting dry-run output, check the current project budget state with a separate live read:

   - `budget_lines` count for the project.
   - Sum of `budget_lines.original_amount`.
   - Existing `project_budget_codes` count.

   If the existing total already matches the workbook original budget total, do not import blindly. Report that the budget appears already imported and identify whether the workbook only has missing zero-dollar mapping rows.

```bash
python3 scripts/import_legacy_budget.py --input /path/to/budget.xlsx --project <project-id> --import --dry-run
```

Treat these as expected setup warnings:

- `Would create missing cost code ...`
- `Would add project budget code ...`
- `Would reactivate project budget code ...`

Treat these as blockers until understood:

- Missing Supabase credentials.
- Cannot infer cost type from the `Budget Code` description suffix.
- Multiple active projects matched.
- Cost type not configured.
- Duplicate budget lines when the user expects a clean project.
- Existing `budget_lines` total already matching the workbook total.

5. Only run the real import when the user clearly asks to import.

```bash
python3 scripts/import_legacy_budget.py --input /path/to/budget.xlsx --project <project-id> --import
```

6. Verify with a separate live read.
   - `budget_lines` count for the project.
   - Sum of `budget_lines.original_amount`.
   - `projects.budget`.
   - Any duplicate or extra `project_budget_codes` that could confuse downstream selectors.

## Important Semantics

- The importer imports budget structure and `Original Budget` only.
- It does not import actuals, direct costs, commitments, pending cost changes, forecasts, or projected over/under.
- Existing cost and commitment values should arrive through the appropriate sync/import paths, not this budget-line importer.
- Keep source descriptions unchanged unless the user explicitly approves cleanup.
- Include zero-original-budget rows by default so actuals/commitments can map to budget codes later.

## Commands

List projects:

```bash
python3 scripts/import_legacy_budget.py --list-projects --project-query "<query>"
```

Convert:

```bash
python3 scripts/import_legacy_budget.py --input /path/to/file.xlsx --convert-only
```

Dry-run:

```bash
python3 scripts/import_legacy_budget.py --input /path/to/file.xlsx --project <id> --import --dry-run
```

Import:

```bash
python3 scripts/import_legacy_budget.py --input /path/to/file.xlsx --project <id> --import
```

## Reporting Back

Always include:

- Target project id, project number, and project name.
- Prepared/imported row count.
- Original budget total.
- Converted CSV path.
- Dry-run warnings grouped as expected setup versus blockers.
- Whether the real import was run.
- Post-import verification if imported.
- Recommended next step.