---
name: office-docs-builder
description: Generates professional Word (.docx), PowerPoint (.pptx) and Excel (.xlsx) files from data or an outline using scripted libraries, with consistent styling, real formulas, native charts and a verification pass. Use when the deliverable must be an Office file — reports, proposals, decks, financial models, data exports — rather than markdown or HTML.
license: MIT
compatibility: Python 3.10+ with python-docx, python-pptx and openpyxl (pip install python-docx python-pptx openpyxl), or Node with docx, pptxgenjs and exceljs. LibreOffice (soffice) optional for rendering checks and PDF export.
metadata:
  category: productivity
  version: "1.0.0"
---

# Office Docs Builder

Office files are judged on opening: does it look intentional, do the numbers compute, do the slides fit? Build them with code so they are reproducible, then verify by reading the file back.

## Step 0 — Choose format and gather content

- **docx** for narrative documents: reports, proposals, memos, SOPs, letters.
- **pptx** for presentations: one message per slide, spoken alongside.
- **xlsx** for anything with numbers someone will edit or recalculate.

Collect the content first: outline, data (CSV/JSON), brand basics (font, two colours, logo path), audience and length. If a template file exists, use it (`Document('template.docx')`, `Presentation('template.pptx')`) and its styles/layouts instead of inventing new ones.

## Step 1 — Plan the structure before coding

Write the outline as a data structure (list of sections/slides/sheets with their content) and generate from it. This keeps content separate from styling and makes revisions cheap.

## Word (.docx) rules

- Use built-in styles (`Title`, `Heading 1–3`, `Normal`, `List Bullet`, `Caption`); modify the style once rather than formatting runs individually.
- Set page margins, default font and size on the document; add page numbers in the footer and a table of contents field for documents over five pages (TOC field updates on open; tell the user).
- Tables: header row bold with shading, repeat header on page break, consistent column widths, numbers right-aligned.
- Images: `add_picture` with width in inches; add captions.
- Headers/footers with title and date; cover page for formal reports. Use `space_after`, not empty paragraphs, for spacing.

## PowerPoint (.pptx) rules

- Pick one layout family from the template and stick to 16:9.
- Every slide: an action title (a sentence stating the takeaway, not "Results"), at most five bullets or one chart or one visual, speaker notes with the narrative.
- Use native charts (`chart_data` in python-pptx / `addChart` in pptxgenjs) so numbers remain editable; never paste chart screenshots.
- Text must fit: cap titles at ~60 characters and body at ~90 words; set autofit off and check overflow by reading shape text lengths.
- Consistent typography: two sizes for body (18–24 pt) and titles (28–36 pt); brand colours from the template theme.
- Include section divider slides for decks over 15 slides and a closing slide with next steps.

## Excel (.xlsx) rules

- One sheet for inputs, one or more for calculations, one for outputs/summary; raw data on its own sheet as a proper table.
- Write **formulas**, not computed values (`ws['D2'] = '=B2*C2'`), so the model stays live. Use absolute references for assumptions (`$B$1`).
- Freeze header rows, apply number formats (`'#,##0.00'`, `'0.0%'`, dates), set column widths, bold headers with fill.
- Named ranges for key assumptions; data validation lists for categorical inputs.
- Add native charts with openpyxl/exceljs referencing ranges.
- No merged cells inside data regions; no formulas referencing empty ranges.

## Step 2 — Generate

Write a single script (`build_<name>.py`) that reads the content structure and produces the file into an `out/` folder. Keep styling in one place (constants or a small `theme` dict). Re-running must overwrite cleanly.

## Step 3 — Verify by reading the file back

- Reopen with the same library and assert: expected section/slide/sheet count, no empty slides, every table has a header, no text box exceeds its capacity, formulas present where expected.
- Recalculate formulas: `soffice --headless --convert-to xlsx --outdir tmp out/model.xlsx` then read values with `openpyxl` `data_only=True`; check for `#REF!`, `#DIV/0!`, `#NAME?`.
- Render to PDF for a visual check when possible: `soffice --headless --convert-to pdf out/deck.pptx` and inspect page count and any overflow.
- Open metadata: set `core_properties.title`, `author`, remove template placeholder text.

## Output format

Report: the generated file path(s), the build script path, a summary of structure (sections/slides/sheets), verification results (counts, formula recalculation status, rendered-page count), and any content that was assumed or left as a placeholder.

## Checklist

- [ ] Built from a script, re-runnable.
- [ ] Uses template/theme styles; no ad-hoc fonts or colours.
- [ ] Charts and formulas are native, not images or pasted numbers.
- [ ] Verified by re-reading and, where possible, rendering.
- [ ] No placeholder text ("Lorem", "Click to add title") remains.
- [ ] File named clearly with a version or date.

## Pitfalls

- python-pptx cannot compute text overflow; estimate by character count and keep margins generous.
- openpyxl does not evaluate formulas; do not read `data_only=True` from a file you just wrote and expect values.
- Very large xlsx writes: use `write_only=True` mode and avoid per-cell styling.
- Editing an existing docx with tracked changes or complex numbering can corrupt structure; prefer generating fresh from a template.
- Fonts not installed on the reader's machine will substitute; stick to Calibri, Arial or Aptos.