/idfa-ops

name: idfa-ops
description: >-
  Named Range operations for IDFA-compliant Excel models. Provides scripts
  to write assumptions, read results, inspect model structure, audit compliance,
  and trigger deterministic recalculation. Use alongside the idfa-financial-architect
  methodology skill. Activate when the agent needs to programmatically interact
  with an Excel financial model — reading, writing, auditing, or recalculating.
license: Proprietary
metadata:
  author: Panaversity
  version: "2.0"
  homepage: https://panaversity.org
  requires: python>=3.10

IDFA Operations

Scripts for programmatic interaction with IDFA-compliant Excel financial models.

---

When to Use This Skill

Activate when the `idfa-financial-architect` methodology skill calls for model interaction:

• **Writing assumptions** — setting Named Range input values
• **Reading results** — retrieving calculated outputs after recalculation
• **Inspecting structure** — listing all Named Ranges, formulas, and dependencies
• **Auditing compliance** — checking all four IDFA guardrails
• **Recalculating** — triggering deterministic formula evaluation via LibreOffice

This skill provides the HOW. The methodology skill provides the WHAT.

---

Prerequisites

| Dependency | Required | Purpose | | -------------------- | ---------------- | ------------------------------------ | | Python 3.10+ | Yes | Script runtime | | uv | Yes | PEP 723 inline dependency resolution | | LibreOffice | Yes (for recalc) | Deterministic formula evaluation | | Anthropic xlsx skill | Recommended | Provides battle-tested recalc.py |

Scripts use PEP 723 inline metadata — `uv run` handles dependency installation automatically. Zero manual `pip install` needed.

---

Operations Reference

| Operation | Command | What It Does | | ------------------ | ---------------------------------------------------------------------- | -------------------------------------------------- | | Write assumption | `uv run scripts/idfa_ops.py write <file> <name> <value>` | Set a Named Range input value | | Read result | `uv run scripts/idfa_ops.py read <file> <name> [name2...]` | Read Named Range value(s) | | Inspect model | `uv run scripts/idfa_ops.py inspect <file>` | List all Named Ranges, values, formulas | | Read formula | `uv run scripts/idfa_ops.py formula <file> <name>` | Return the formula text for a Named Range | | Create Named Range | `uv run scripts/idfa_ops.py create-range <file> <name> <sheet> <cell>` | Create a new Named Range definition | | Recalculate | `uv run scripts/recalc_bridge.py <file>` | Trigger LibreOffice deterministic recalculation | | Audit compliance | `uv run scripts/idfa_audit.py <file>` | Check all four IDFA guardrails, return JSON report |

All script paths are relative to this skill's directory (`skills/idfa-ops/`).

---

The Write-Recalculate-Read Pattern

The fundamental interaction pattern for IDFA model operations. The agent reasons about what values to set, but the spreadsheet engine performs all arithmetic.

# Step 1: Write assumption
uv run scripts/idfa_ops.py write model.xlsx Inp_Rev_Y1 12000000

# Step 2: Recalculate (LibreOffice evaluates all formulas)
uv run scripts/recalc_bridge.py model.xlsx

# Step 3: Read results
uv run scripts/idfa_ops.py read model.xlsx Gross_Profit_Y1 Gross_Profit_Y2 Gross_Profit_Y3

**Step 1** writes the assumption to the Named Range. The value is stored but dependent formulas are not yet recalculated.

**Step 2** triggers LibreOffice to evaluate every formula in the workbook deterministically. This is essential — openpyxl cannot evaluate formulas.

**Step 3** reads the recalculated results. The values returned are the model's deterministic output, not the agent's estimate.

---

Composing with the xlsx Skill

When Anthropic's `xlsx` skill is also installed, `recalc_bridge.py` automatically delegates to the xlsx skill's `recalc.py` for LibreOffice-based formula evaluation. When only `idfa-ops` is installed, `recalc_bridge.py` runs its own LibreOffice macro.

The interface is identical either way — the agent calls the same command regardless of which recalculation backend is available.

---

Output Formats

All scripts output JSON to stdout for agent consumption.

**Success example (read):**

{
  "status": "ok",
  "values": { "Gross_Profit_Y1": 4000000, "Gross_Profit_Y2": 4510000 }
}

**Success example (inspect):**

{"status": "ok", "named_ranges": [...], "count": 16}

**Error example:**

{ "error": "Named Range not found: Bad_Name" }

Exit codes: `0` = success, `1` = Named Range not found, `2` = file/usage error.

---

Output Best Practices

Every task that modifies or analyses a model MUST produce a **Markdown results file** saved to the output directory. The xlsx file alone is insufficient — a text artifact is needed for review, grading, and audit trail.

For multi-step operations (what-if, goal-seeking, multi-write scenarios):

1. Document each step: what command was run, what was returned 2. Include a summary table with before/after values 3. State the methodology: "All values obtained via write-recalculate-read pattern" or "Computed via formula tracing (LibreOffice unavailable)" 4. Save as `<task>_results.md` alongside the modified xlsx

This is not optional — the results file IS the deliverable. The xlsx is the artifact that proves it.

---

Error Handling

| Error | Exit Code | Agent Action