/brand-xlsx

name: brand-xlsx
description: >-
  Brand-aware Excel engine. Use to (1) EXTRACT a company's brand from a .xlsx template into a
  reusable "Brand Profile", (2) COMPREHEND the template with the model (optional), (3) VERIFY it,
  (4) GENERATE a new on-brand .xlsx from a GridDocument fill manifest. Trigger on "extract our
  brand", "use our workbook template", "generate a branded workbook from our profile", or when a
  ./brand-kit exists. For one-off spreadsheet edits with no saved brand profile, use the normal
  xlsx skill instead. NOT for .docx (brand-docx), .pptx (brand-pptx), or PDFs.

brand-xlsx

Use this skill when the user wants reusable branded Excel/workbook generation from a company `.xlsx` template and variable user-provided data.

This is an AI-agent skill for Codex and Claude Code. The user should describe the workbook/model they want filled; the agent maps that request to named cells and named regions, invokes the internal Python engine, verifies the output, and returns the generated `.xlsx`.

The seven verbs: three deterministic + four model-assisted

Every brand skill (`brand-docx`, `brand-pptx`, `brand-xlsx`) implements the same contract. The deterministic core is **extract / verify / generate**; on top of it sit the optional learning verbs **comprehend / learn / propose-overrides / refine**, each fail-closed (the engine validates every proposal and authors every value).

| Verb | Input | Output | |---|---|---| | **extract** | a company `.xlsx` template | a reusable Brand Profile | | **comprehend** *(optional, model-driven)* | a saved profile + a model-authored `comprehension.json` | the profile with a validated, cached `comprehension` block | | **verify** | a saved Brand Profile | QA findings + a verdict | | **generate** | data (a GridDocument) + a profile | a new on-brand `.xlsx` | | **learn** *(deterministic distillation)* | the profile's cross-run generation history | recurring QA findings distilled into shell-frozen overrides, advisory until `--accept` | | **propose-overrides** *(model-driven)* | the recurring remainder `learn` could not bind + a model-authored proposal | shell-backed corrections through the same fail-closed sink, advisory until `--accept` | | **refine** | end-of-generation user feedback (text or a screenshot) as a `refinement.json` delta | the existing comprehension overlaid for FUTURE generations, advisory until `--accept` |

`comprehend` is **optional**: `generate` works on the deterministic profile alone. See [reference/comprehension.md](reference/comprehension.md) for the full step.

Hard Rules

• Treat `python scripts/cli.py ...` as an internal engine command, not the user-facing workflow.
• `scripts/cli.py` is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set `BRAND_DOCS_ROOT` to override). Never guess deeper paths like `scripts/brandkit/...`.
• Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
• Extract opens the source template read-only and saves `brand-kit/<name>/template/shell.xlsx` byte-for-byte.
• Generate opens the saved shell and resolves every named cell/region through `profile.json`.
• Do not put style names, colors, fonts, or brand identifiers in a GridDocument.
• If the user did not provide a template or enough data, ask for the missing input.
• Return the generated file path plus a QA summary.
• Consult `profile.json.artifact_catalog` before generation when the user asks to mimic a specific piece of the template.

Preflight (always first)

Before doing any work, run:

python scripts/cli.py doctor

Use its output to decide the run mode:

• If a required Python dependency is missing, install/repair it before extraction

or generation; the core engine is not ready.

• If only visual renderers are missing or unusable (`soffice` plus `pdftoppm` or

optional PyMuPDF/`fitz`), the core L0 workflow can still run, but a full visual audit cannot be claimed. Tell the user what is missing, include the install/repair hint printed by `doctor`, and either proceed with degraded QA or install the renderer first.

• If optional OCR (`tesseract`) is missing, the visual audit can still run, but

rendered residual-text proof is incomplete. Report that limitation when judging stale placeholders or field caches.

• For `--qa deep` or `--qa strict`, prefer repairing/installing renderers before

generation. If the environment cannot run them, `deep` generates a degraded manifest and `strict` fails with a visual proof blocker.

Agent Workflow

1. Run the dependency preflight above and report any degraded capability. 2. Determine the brand name and locate the user-provided `.xlsx` template. 3. If no matching `brand-kit/<name>` exists, **extract** one. 4. **Comprehend** the template (optional, model-driven; see below). Skip when a current comprehension is already cached or no model is available. 5. Convert the user's tabular/model data into `GridDocument` JSON. 6. **Generate** the `.xlsx` with the internal engine. 7. Run **QA** and report any warnings honestly. 8. **Feedback** (only after returning the file): invite a refinement of the understanding for future workbooks (see below).

Before generation, inspect `profile.json.artifact_catalog` when the user asks to mimic a specific workbook piece. It records OOXML parts, named ranges, formulas, sheet dimensions, table names, merged cells, row/column sizing, cell styles, and number formats.

Authoring the GridDocument

The Grid is where "correct workbook" becomes "great workbook". Author it region-first, against the profile, never cell-address-first:

1. **Read `brand-kit/<name>/PROFILE.md` before writing a fill.** It lists the named-region roles, the brand cell styles, and the palette tokens. Address content to NAMED regions from that table; the engine fills the template's real ranges.