# Report style: writing standard + design system

The audit is the practitioner's own deliverable, meant to be handed to their client or stakeholder. So the report is white-label: it carries the practitioner's name, optional logo, and optional accent color, never anyone else's brand. This file holds the writing rules and the design system. It travels inside the Skill so the rules are always available.

## Writing rules (apply to the report's narrative)

These rules govern your analysis and framing. Quotes pulled from the client's assets are reproduced verbatim, even if the client broke these rules. Everything you write around those quotes follows them.

**Never use em dashes.** Use a period, a semicolon, a comma, or parentheses. Restructure the sentence if you have to. This one is absolute.

**Voice:** senior practitioner talking to a peer. Warm, direct, and unhedged. No condescension, no flattery, no hype. Confident without performing seniority. Mix short and long sentences for rhythm.

**Always:**
- Sentence case for headings and titles.
- Oxford comma, every time.
- Contractions. Write the way you talk.
- Straight quotes, never curly or smart quotes.
- Specific numbers. "4 of 10 elements are Contradictory" beats "several elements conflict."
- Cut the lead-in. Start with the substance.

**Never:**
- Never open a section with filler like "In today's competitive landscape" or "It's worth noting that."
- Never use the "it's not X, it's Y" antithesis reframe. It reads as AI slop.
- Never use hype or AI-tell words. Banned list below.
- Never flatter the reader or hedge a finding that should be stated plainly.

**Banned words and phrases** (do not use in the report narrative): delve, tapestry, vibrant, pivotal, crucial, landscape (figurative), intricate, interplay, showcase, foster, underscore (verb), enhance, garner, testament, renowned, groundbreaking, profound, vital, seamless, leverage (verb), unlock, empower, robust, holistic, elevate, navigate (figurative), "serves as," "stands as," "a testament to," "it's worth noting," "in today's [x] world," "let's dive in," 10x, game-changing, revolutionary, supercharge, level up, utilize, "in order to," really, very, super.

Before you deliver, reread the report once and cut any sentence that could be deleted without losing information.

## Write findings so a busy client gets them on first read

Every finding must be plain and literal: say what is wrong, where it is, and why it matters, in the fewest clear words. One point per finding. Do not dramatize or editorialize. Skip the rhetorical build-up ("this isn't subtle"), the metaphors ("on its own home turf"), and the urgency theater ("live, right now"). If a sentence would make the reader ask "what does that actually mean?", rewrite it literally. A client should be able to act on each finding without decoding it.

**Too dramatic (do not write like this):** "The headline finding isn't subtle: the footer bio on every single page, including the three you just rebuilt, still says the old money-first pitch, and it sits a few inches below new hero copy that says something almost opposite. That's the new positioning getting undercut on its own home turf, live, right now."

**Plain (write like this):** "The footer bio on every page still uses the old money-first pitch. It sits directly below the new hero copy, which says the opposite. So the old positioning is still live on every page, including the three you just rebuilt."

## The author profile (who the report is from)

The report's authorship comes from a small profile the Skill sets up once and reuses (see the Execution steps and `references/audit-schema.md`):

- **Name or practice** goes in the "Prepared by" line and the footer.
- **Logo** (optional) is a path to the practitioner's own image file. If given, it prints at the top of the cover and small in the footer. If not, the report is a clean, name-only cover. No logo ships with the Skill.
- **Accent color** (optional) is a single hex value. It sets the one accent used across the report. If not given, the report uses the neutral default.

## Design system

The report uses a light, airy layout with a two-tone accent, in the style of a clean progress-report template: a pale-wash cover, a thin accent bar across the top of each content page, accent section titles, and an accent table header with soft zebra rows. Both accents are swappable per practitioner, so it can match anyone's brand or stay neutral.

**Neutral base (fixed):** background `#FCFCFA`, panel `#EEF1F4`, ink `#1B1C1B`, muted text `#5F635F`, hairline `#E4E7E5`.

**Primary accent (swappable, `accent`):** default is a clear cyan `#1F9DB3`. Carries the structure: the cover title and cover bar, the running top bar on content pages, the section titles, the extraction-matrix header, the priority numbers, the gap-type labels, and the Your Strategic Take outline. Use a mid-to-dark color so white text reads on the matrix header.

**Secondary accent (swappable, `accent2`):** default is a light cyan `#8AD4DF`. Carries the lighter touches: the short rule under each section heading, the zebra rows in the matrix (as a soft tint), and the next-step box (as a soft tint). The cover wash is a very pale version of the primary accent.

Set both per practitioner in their profile. For example, a pink-and-teal brand sets `accent` to its pink and `accent2` to its teal.

**Rating colors (fixed status colors, not brand).** These signal meaning, so they stay constant no matter the accent:
- Aligned = green (text `#1E7A46`, fill `#E6F4EC`).
- Drifting = amber (text `#B87514`, fill `#FBEED6`).
- Contradictory = red (text `#C0392B`, fill `#FBE9E7`).
- Absent = grey (text `#6B7280`, fill `#EDEEF0`).

All of this is implemented in `scripts/build_report.py`. You never set colors by hand; you fill `audit.json` and the script applies the system.

## Type

The fonts are chosen to read executive and to render natively in Word, where .docx files open. This is a product that lands on strangers' computers, so the type has to hold up without any brand fonts installed.

- Headings and title: Cambria (serif). Sharp, modern, authoritative. The accent phrase in the title is italic.
- Body: Calibri. Tight and corporate, the standard professional-document sans.
- Labels, section eyebrows, table headers, meta: Calibri, uppercase, letter-spaced, for crisp contrast against the serif headings.

Cambria and Calibri are the Microsoft Office standard pair, so they render natively in Word on Windows and Mac. All three are set in `scripts/build_report.py`. If you ever change the pairing, stay with fonts that ship with Office or every OS (for example Cambria, Calibri, Georgia, Arial, Times New Roman) so the document never silently substitutes on a reader's machine.
