dl-databook-charts - SKILL.md Agent Skill

name: dl-databook-charts description: >- Restores the standardized chart inventory (nine charts on HistFin Charts / NWC / Seasonality) on an Overland deal Databook (.xlsx) whose charts were gutted into empty shells by an openpyxl save. Use when the user asks to "restore the Databook charts" or "fix the charts" after dl-databook-financials populates the workbook — and again after every dl-databook-kpi call. Extracts a deterministic chart-spec manifest from the bundled blank template (the live OOXML, never guessed), then transplants the template's own chart/drawing/style parts into the populated vS workbook at the zip level, leaving the sheet-name-qualified source ranges to drive Excel's recomputation on open — gated by a machine-verified preservation gate (exactly the standardized inventory restored; every other part identical to the input; idempotent). Not for borrower-specific operational pie charts (out of scope), not for chart data population, not for other workbooks.

Restoring the Databook standardized charts

Overview

dl-databook-financials populates the Databook SUCAP + FinInputs tabs with openpyxl, which guts the workbook's nine standardized charts (HistFin Charts, NWC, Seasonality) into content-dead, de-styled shells on save. This skill restores them by transplanting the bundled template's own chart OOXML parts into the populated vS workbook. The deliverable is the chart-restored .xlsx (a deal-named copy) — not a regenerated workbook, not a text summary.

It runs downstream on the dl-databook-financials vS output and touches only the chart/drawing OOXML; the upstream value-population engine is never read, modified, or depended on. The transplant is fixed, not generative — the standardized inventory is invariant — and sits behind a machine-verified preservation gate. Never regenerate charts with the openpyxl chart API (it produces empty shells); never re-point a chart source reference (sheet names are invariant — the transplant moves bytes, not references).

Template asset (bundled — no upload required):

assets/databook-template.xlsx

Source of truth for the transplant. Never write back to it.

References (read before first use):

reference/chart-inventory.md — the invariant inventory, per-anchor chart detail, the direct sheet-name-qualified binding, the transplant part set, what is out of scope.
reference/restore-mechanics.md — the measured openpyxl gap, why a zip-level transplant (not the chart API), the algorithm, the five preservation-gate checks, the escalation rules, and what is NOT touched.

Dependencies

pip install openpyxl

openpyxl is used only to model the chart-stripped input in the self-test and to sanity-open the restored file; the transplant + gate use only the standard-library zipfile and xml.etree. Load workbooks with data_only=False if you open them at all.

Workflow

Copy this checklist and check items off as you go:

Databook charts progress:
- [ ] Step 0: Orient (deliverable, classification)
- [ ] Step 1: Confirm the input is a populated vS Databook
- [ ] Step 2: Extract the chart-spec (scripts/extract_chart_spec.py)
- [ ] Step 3: Restore + verify the gate (scripts/restore_charts.py)
- [ ] Step 4: Confirm the structured output

Step 0 — Orientation

Deliverable: the chart-restored .xlsx (a deal-named vS copy), identical to the input vS workbook except the restored standardized chart OOXML — not a regenerated workbook, not a summary.
[INSUFFICIENT DATA — <what is missing>] is the only uncertainty marker. Never fabricate or empty-out a chart; a missing chart source sheet is flagged and the run refuses — never papered over.

Step 1 — Confirm the input

The input is the deal vS Databook produced by dl-databook-financials (<Company>_Databook_vS.xlsx). Confirm it is that workbook. The skill does not populate HistFin/Seasonality/NWC data — it restores the charts over whatever those ranges address. If the input is a finished borrower book carrying borrower-specific operational pie charts, Step 2/3 will escalate (out of scope here — borrower-specific cuts belong to dl-databook-kpi).

Step 2 — Extract the chart-spec

python scripts/extract_chart_spec.py assets/databook-template.xlsx \
    --out chart_spec.json

Resolves the standardized inventory from the live template zip (never a from-memory guess), asserts the invariant contract (9 charts over 3 drawings; HistFin Charts:4 / NWC:1 / Seasonality:4; only bar/line plot types; zero operational-belt pie/doughnut), and writes the manifest. A non-standard template escalates with no chart_spec.json (exit 2) — refer to an analyst. See reference/chart-inventory.md.

Step 3 — Restore + verify the preservation gate

python scripts/restore_charts.py <Company>_Databook_vS.xlsx \
    --spec chart_spec.json \
    --template assets/databook-template.xlsx \
    --out <Company>_Databook_vS.xlsx

Transplants the 27 template parts (9 charts, 3 drawings, 3 drawing rels, 8 style/colors, 4 chart rels) and adds only the missing style/colors [Content_Types] overrides, then verifies the preservation gate in memory before any file is written:

exactly the manifest's transplant parts are written, identical to the template (sha256-pinned);
every other part is identical to the input vS workbook;
the [Content_Types] delta is exactly the manifest's style/colors overrides;
every restored chart's source sheet(s) exist by name in the vS workbook — else [INSUFFICIENT DATA — <chart>:<sheet>], refuse;
the operation is idempotent (re-run leaves part set/bytes unchanged).

Any gate violation ⇒ no file written, vS unchanged (exit 3). A bespoke / operational-belt vS, or a non-standardized manifest ⇒ refuse with a named reason, no output (exit 2). No chart reference is re-pointed. See reference/restore-mechanics.md.

Step 4 — Structured output

The structured content conforms to the skill's structured output schema (the chart-spec manifest, re-emitted verbatim). The gate record, escalations, and classification fields are internal capture and never reach the .xlsx.

Escalation

Halt with a named reason and no output (record in escalations) when: the template/vS chart inventory is not the invariant standardized set; any chart carries a forbidden plot type (borrower-specific operational charts — out of scope here); a chart binds to a foreign sheet; the vS carries a chart part beyond the standardized nine; or a chart source sheet is absent from the vS ([INSUFFICIENT DATA — …]). Never auto-wire a bespoke inventory; never fabricate an empty chart — refer to an analyst.

Classification & review state

The Databook is internal (CONFIDENTIAL, MNPI) — never outbound; no RESTRICTED input is read (charts carry no IC content). The output is a draft pending human review: the draft signal is the vS filename — no [DRAFT — HUMAN REVIEW REQUIRED] banner in the workbook body, because the file is an in-place-edited production template and a banner would corrupt it. A reviewer approves and finalizes; never approve, finalize, or issue. [INSUFFICIENT DATA — <what is missing>] for any gap — never fabricate.

Runtime

The scripts run where Python is available: Claude Desktop or claude.ai with code execution enabled. In the Excel add-in (or any chat without code execution), do not attempt to rebuild or re-insert the charts in-document — the zip-level transplant and its preservation gate cannot run there, and an improvised chart rebuild produces empty shells. Say so and direct the user to run the skill in Claude Desktop.