Professional Word Output

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

Generate world-class, professionally designed Microsoft Word (.docx) documents that look like a designer and communications specialist worked on them together — not AI output. Use when producing any .docx file: reports, proposals, manuals...
The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

Do Not Use When

The task is unrelated to professional-word-output or would be better handled by a more specific companion skill.
The request only needs a trivial answer and none of this skill's constraints or references materially help.

Required Inputs

Gather relevant project context, constraints, and the concrete problem to solve; load references only as needed.
Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

Workflow

Read this SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

Quality Standards

Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

Anti-Patterns

Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
Loading every reference file by default instead of using progressive disclosure.

Outputs

A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
References used, companion skills, or follow-up actions when they materially improve execution.

Evidence Produced

Category	Artifact	Format	Example
Release evidence	Generated Word document	Branded .docx artefact compliant with the professional-word-output design standard	`docs/output/report-2026-04-16.docx`

References

Use the references/ directory for deep detail after reading the core workflow below.

Two things kill document quality equally: bad design and bad writing. A document must pass both tests. This skill addresses both.

Reference files (read when needed):

references/typography-layout.md — fonts, spacing, margins, colour palettes, visual hierarchy
references/written-communication.md — structure, clarity, tone, anti-patterns
references/word-features.md — styles, TOC, tables, images, sections, cover pages, watermarks
references/quality-checklist.md — pre-delivery checklist (run before every delivery)

The Standard

Every document produced must pass this bar: a professional communications specialist and a document designer would both be satisfied. This means:

Every typographic decision is intentional and consistent
The writing is clear, structured, and free of AI-slop vocabulary
Navigation elements (TOC, headers/footers, page numbers) are complete and correct
Visual hierarchy guides the reader without effort
The document looks the same on any machine (styles, not direct formatting)

Production Pipeline

Documents are produced via Pandoc + python-docx + reference.docx template:

Markdown source (structured content)
    ↓ pandoc --reference-doc=templates/reference.docx
.docx (styles applied from reference.docx)
    ↓ manual python-docx post-processing (cover page, TOC, header/footer)
Final .docx → PDF export

Project export contract

Every project that generates .docx deliverables must include these project-root paths:

projects/<ProjectName>/export/
projects/<ProjectName>/export-docs.ps1
projects/<ProjectName>/export-docs.sh

Build .docx files in their canonical phase folders first. Then run the project export script so export/ contains a flat copy of every generated Word deliverable, excluding files already inside export/.

Build commands

# Single document
pandoc source.md -o output.docx --reference-doc=templates/reference.docx

# With table of contents
pandoc source.md -o output.docx --reference-doc=templates/reference.docx --toc --toc-depth=3

# Rebuild reference.docx from scratch
python scripts/create-reference-docx.py

Style System

Pandoc maps Markdown elements to named Word styles in reference.docx. Never bypass this with direct formatting.

Markdown element	Word style
`# Heading`	Heading 1
`## Heading`	Heading 2
`### Heading`	Heading 3
`#### Heading`	Heading 4
Body paragraph	Normal
```code block```	Source Code / Verbatim
`inline code`	Verbatim Char
`> blockquote`	Block Text
Table	Table Grid
YAML `title:`	Title
YAML `subtitle:`	Subtitle
`Caption` below figure/table	Caption

If a style needs to change, change it in reference.docx — never in the document directly.

Heading Flow & Page Break Rules

These rules are mandatory. They determine how the document breathes across pages and whether the reader can follow the structure without effort.

Rule 1 — Heading 1 always starts a new page

Every # Heading 1 forces a page break before it. Major sections never share a page with the section that precedes them. This makes the document scannable: readers flipping through pages immediately see where each chapter/section begins.

Word setting: Paragraph → Line and Page Breaks → Page break before = ON

python-docx:

from docx.oxml.ns import qn
from docx.oxml import OxmlElement

h1 = doc.styles['Heading 1']
h1.paragraph_format.page_break_before = True
h1.paragraph_format.keep_with_next = True   # heading never orphaned alone

Rule 2 — Heading 2 and Heading 3 stay with their first paragraph

If the heading plus its first following paragraph do not entirely fit on the current page, the whole unit moves to the next page. A heading that appears at the bottom of a page with its content on the next page is a design failure.

Word settings on Heading 2 and Heading 3:

Paragraph → Line and Page Breaks → Keep with next = ON
Paragraph → Line and Page Breaks → Keep lines together = ON

Word setting on Normal / body paragraphs:

Paragraph → Line and Page Breaks → Keep lines together = ON

This combination means: the heading is glued to the paragraph that follows it, and that paragraph will not be split across pages. If the pair doesn't fit, both move to the next page.

python-docx:

for style_name in ['Heading 2', 'Heading 3']:
    style = doc.styles[style_name]
    style.paragraph_format.keep_with_next = True
    style.paragraph_format.keep_together = True

# Body paragraphs: never split mid-paragraph
doc.styles['Normal'].paragraph_format.keep_together = True

Rule 3 — Widow and orphan control is always on

No paragraph's first line appears alone at the bottom of a page (orphan), and no paragraph's last line appears alone at the top of a page (widow).

Word setting: Paragraph → Line and Page Breaks → Widow/Orphan control = ON (this is the Word default but must be confirmed in reference.docx).

doc.styles['Normal'].paragraph_format.widow_control = True

Summary table — paragraph flow settings per style

Style	Page break before	Keep with next	Keep lines together	Widow/orphan
Heading 1	ON	ON	—	—
Heading 2	OFF	ON	ON	—
Heading 3	OFF	ON	ON	—
Heading 4	OFF	ON	ON	—
Normal	OFF	OFF	ON	ON
Body Text	OFF	OFF	ON	ON
Caption	OFF	OFF	OFF	OFF

What this looks like in the document

Opening a document and scanning: each major section (H1) occupies its own visual territory — top of a fresh page
Reading through body content: the eye never arrives at an H2/H3 sitting stranded at the bottom of a page; the heading is always above its content
Short paragraphs never lose their first or last line to a page break
The result is a document that reads like it was typeset, not generated

Typography Specification

Read references/typography-layout.md for full font stacks and spacing tables. The standard corporate stack:

Element	Font	Size	Colour
Title	Calibri Light	28pt Bold	#1F3864
Heading 1	Calibri Light	16pt Bold	#1F3864
Heading 2	Calibri Light	13pt Bold	#2E5D8A
Heading 3	Calibri	11pt Bold	#4472C4
Body / Normal	Calibri	11pt Regular	#262626
Code	Consolas	9.5pt Regular	#1A1A1A
Caption	Calibri	9pt Regular	#595959
Header/Footer	Calibri	9pt Regular	#595959

Heading 1 visual anchor: 4.5pt navy left border bar — applied via style paragraph border, not manual formatting.

Spacing Rules

Never press Enter twice to create space. Use style space-after settings.

Style	Before	After	Line
Heading 1	20pt	6pt	Single
Heading 2	14pt	4pt	Single
Heading 3	10pt	3pt	Single
Normal	0pt	6pt	1.15×

Document Structure (every document)

1. Cover Page

---
title: "Project Name — Document Title"
subtitle: "Document Type — Category"
date: "YYYY-MM-DD"
version: "1.0"
status: "Draft | Review | Final"
---

Followed immediately by an ownership table:

| | |
|---|---|
| **Project** | Project Name |
| **Owner** | Organisation Name |
| **Author** | Author Name |
| **Version** | 1.0 Draft |
| **Date** | 2026-04-05 |
| **Classification** | Confidential — Internal Use Only |

Cover page has no header/footer (set different_first_page_header_footer = True).

2. Table of Contents

Required for all documents longer than 5 pages. Generated automatically from Heading 1/2/3 styles.

3. Body Content

Three-part structure at every level:

Introduction — context and purpose (what this section covers)
Development — main content, evidence, detail
Conclusion — key takeaway or next action

4. Headers and Footers

Header: Document title (field) right-aligned, thin grey rule below.

Footer: "Page X of Y" centred, confidentiality notice left, print date right.

Table Design

Tables must look designed, not dumped. Read references/word-features.md → Tables section.

| Column A | Column B | Column C |
|---|---|---|
| Data | Data | Data |

Standard table spec:

Header row: Navy fill (#1F3864), white bold 10pt text
Banded rows: light blue tint (#F2F7FD) / white alternating
Outside border: 1pt, #1F3864
Inside grid: 0.5pt, #BBBBBB
Caption below every table: "Table N: Description"
Header row repeats on every page for tables spanning multiple pages

Images and Figures

Every figure needs a caption below: "Figure N: Description" (Caption style)
Apply a 1pt grey border (#CCCCCC) to framed figures
Minimum 150 DPI for print documents
Use PNG for diagrams; JPEG for photographs
Never stretch images — use corner handles only

Written Communication Standards

Read references/written-communication.md for full guidance. Core rules:

Structure: Inverted pyramid — most important information first, at every level (document, section, paragraph, sentence).

Sentences: 15–20 words average. One idea per sentence. Active voice.

Never use:

"Delve into", "leverage", "robust", "seamlessly", "in today's landscape"
Vague adjectives without metrics ("fast", "powerful", "intuitive")
Passive voice for instructions ("The button should be clicked" → "Click the button")
Undefined acronyms on first use
Numbered lists for non-sequential items
Bullet lists for sequential steps

Always include:

Clear topic sentence opening every section
Logical connectors at paragraph transitions
Examples to illustrate abstract claims
Measurable specifics in place of vague adjectives

Cover Page Design Principles

A professional cover page contains:

Brand bar — full-width colour block (1.5–2 cm height), primary brand colour
Company logo — top-left or centred within brand bar
Document title — 28–36pt, Light weight, high contrast against background
Subtitle and metadata — version, date, status
Ownership table — structured metadata block
No header/footer — the cover page IS the identifier

Watermarks

Apply when document status requires it:

DRAFT — grey diagonal, 50% transparency, 80pt Calibri Semi-Bold
CONFIDENTIAL — grey diagonal, same spec
INTERNAL USE ONLY — same spec

Insert: Design → Page Background → Watermark → Custom Watermark.

Markdown Source Quality Rules

These patterns degrade Word output — do not use them:

Bad pattern	Why	Fix
`*` for bullet lists	Inconsistent in some Pandoc builds	Use `-` only
Setext headings (`---` underline)	Ambiguous, not parsed correctly	Use `#` ATX only
Code blocks inside table cells	Breaks table rendering	Move code outside tables
Raw HTML tags	Does not render in .docx	Use Markdown equivalents
`bold` + `italic` combined	Inconsistent output	Use one or the other
Blank lines instead of spacing	Creates erratic spacing	Let styles handle space

Pre-Delivery

Before every delivery, run references/quality-checklist.md in full. The minimum final actions:

Ctrl+A → F9 — update all fields (TOC, page numbers, dates)
Review → Spelling & Grammar — fix all issues
File → Info → Inspect Document — remove comments, tracked changes, metadata
File → Print → verify print preview (no widows, no blank pages)
Export PDF with accessibility tags enabled
Name file: ProjectName_DocumentType_v1.0_YYYY-MM-DD.docx

Customisation Reference

To change global document styling, edit scripts/create-reference-docx.py:

What to change	Location in script
Heading colours	`NAVY`, `STEEL`, `ACCENT` constants
Body/heading font	`FONT_BODY`, `FONT_HEADING` constants
Code font	`FONT_CODE` constant
Heading 1 border weight	`sz` attribute in `pBdr` block
Footer content	`footer` section
Page size and margins	`section.left_margin` etc.

Rebuild after changes:

python scripts/create-reference-docx.py
bash scripts/build-doc.sh <doc-dir> <output-name>

professional-word-output