Idfa Ops

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

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

Operations Reference

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

When LibreOffice is unavailable, the agent can still write assumptions and read cached values — but the Write-Recalculate-Read pattern cannot complete. The agent should inform the user that results may not reflect the latest assumptions.

Attribution

IDFA Operations is part of the IDFA Financial Architect plugin, developed by the Panaversity team (https://panaversity.org). Proprietary — see LICENSE.