---
name: formatting-check
description: >-
  Finds formatting inconsistency inside a Word document by resolving each paragraph's effective
  formatting through the style chain first, then comparing paragraphs of like kind against each
  other. Catches the near-black run among blacks, the one heading spaced differently from its
  siblings, the stray indent and the tab that should be spaces. Use before sending or signing a
  document that several people have edited.
---

# Formatting consistency check

Formatting drift is what happens to a document that more than one person has touched. A clause is
pasted in from another deal and brings its font with it. A heading is retyped and loses its
spacing. A defined term is edited and one run ends up a point smaller than its neighbors. None of
it is visible while you are reading for meaning, and all of it is visible to whoever receives the
document.

**This check compares the document against itself.** There is no external style guide involved. A
property is wrong only when it disagrees with what this document does everywhere else for that kind
of paragraph.

## Read the styles before you read the text, or you will report nothing

**A `.docx` file is a zip archive, and the formatting you need is split across two parts of it.**
Unzip it and you will find `word/document.xml`, which holds the text and any formatting applied
directly to it, and `word/styles.xml`, which holds the styles and the defaults that everything
else inherits from.

**Almost all of the formatting is usually in `styles.xml`, not in `document.xml`.** In a plain
fourteen-paragraph agreement measured while this skill was written, `document.xml` carried exactly
one explicit font size, one color, one spacing and one indent, while `styles.xml` carried 26 sizes,
267 colors, 197 spacings and 164 style definitions linked by 158 `w:basedOn` references.

**So an agent that reads `document.xml` alone finds almost nothing and reports the document clean.**
That is the failure this section exists to prevent, and it is the worst one available, because a
confident all-clear is indistinguishable from a careful pass.

Resolve each paragraph's **effective** formatting in this order, with each step overriding the one
before it:

1. `w:docDefaults` in `styles.xml`, which is the document-wide floor.
2. The style named by the paragraph's `w:pStyle`, then that style's `w:basedOn` parent, and up the
   chain until a style has no parent. A property set anywhere in that chain applies unless
   something nearer the paragraph overrides it.
3. Direct paragraph properties in the paragraph's own `w:pPr`.
4. Direct run properties in each run's `w:rPr`, which win over everything above for that run.

Only once you hold the effective value for a paragraph can you say whether it differs from its
neighbors. **A paragraph with no explicit formatting is not unformatted**, it is inheriting, and
its effective values are whatever the chain gives it.

## The units will mislead you if you quote them raw

- **`w:sz` and `w:szCs` are in HALF-POINTS.** `w:val="22"` is 11 pt. Report points to the reader,
  never the raw number.
- **`w:spacing` and `w:ind` are in twips**, meaning twentieths of a point, so 1440 to the inch.
  `w:before="480"` is 24 pt.
- **`w:color w:val="auto"` is not a color**, it is an instruction to let the renderer choose, and
  it is usually black. An explicit `000000` and an `auto` may look identical and are different
  values, so say which you are comparing.
- Line spacing depends on `w:lineRule`: `auto` makes `w:line` a multiple in 240ths, while `exact`
  and `atLeast` make it twips.

## What counts as an inconsistency

Compare paragraphs of like kind against each other. Headings at the same level should agree with
each other. Items in one list should agree with each other. Body paragraphs should agree with each
other. **A single differing paragraph among many consistent ones is a finding; a property you
merely find unusual is not.**

Three classes get walked past, so check each deliberately rather than waiting for one to catch your
eye.

**Near-identical colors.** A run at `0A0A0A` among `212121` neighbors, or `333333` among
`000000`, looks like nothing on screen and is a real defect. Compare the hex values rather than
judging by eye, because every near-black reads as black.

**Heading spacing, level by level.** Compare `w:before` and `w:after` across headings of the SAME
level, and treat one heading differing from its siblings as a finding even though nothing about it
looks wrong in isolation. **Absence counts**: if most siblings inherit their spacing and one sets
its own, that one is the outlier. Do this separately for every heading level the document contains,
because finding an outlier at one level tells you nothing about the others, and stopping after the
first level is how this check most often gets half done.

**Leading whitespace.** This is formatting written as text, so no property carries it and you read
it off the start of the paragraph's own content. If the defined terms in a list each start with a
tab and one starts with four spaces, or the reverse, that one is the outlier. Word renders a tab
and a run of spaces almost identically, and the difference is plain in the XML.

**Finish a class before you move on.** When you find one run at the wrong size, look for others;
when you find one misindented list item, look at the other lists. These defects arrive in groups
more often than singly, and a report that names the first and stops reads as though everything
else of that kind had been checked and found clean.

## What to compare

Run level: font family, size, color, and bold, italic, strikethrough and underline.
Paragraph level: alignment, left, right and first-line indent, space before and after, line spacing
and its rule, and list level on list items. **Pay particular attention to a single character, a
single word or one table cell that differs from everything around it**, because those are the
hardest for a reader to catch and the most likely to be accidental.

## What not to report

**Deliberate convention is not drift.** Emphasis on a word, italics on a cited title or a case
name, a bold subject line, a block quotation set a point smaller. These are choices, and telling
the reader to undo them makes the document worse.

Declining to report something needs a reason you can see in the formatting rather than one you
inferred from what the text says. Two reasons qualify. The first is a recognized typographic
convention of the kind just listed. The second is **too few examples to establish a practice**:
where a level has two paragraphs and they differ, neither is the outlier, so say that and leave it
alone, naming both so the reader can see what you compared.

**What does not qualify is guessing at the author's intent.** "Its importance may explain the added
indentation" is a claim about the meaning of the paragraph rather than about its formatting, it
cannot be checked against anything, and it is usually written about something that is drift by
every test above. When your reason for not reporting something is a guess of that kind, report it
and say it might be deliberate. Declining costs the reader a moment; withholding costs them the
fix.

**Say what you could not see.** Reading the XML directly will not show you everything a renderer
shows, so name what you did not inspect rather than implying full coverage. Highlight color,
character styles, small caps, borders, shading, tracked changes and anything in a header, footer or
embedded object each live somewhere you may not have looked.

## What to hand back

Counts first, then findings grouped by the class of defect. For each finding: quote the text that
is wrong, name the property and its effective value in human units, name what the surrounding
paragraphs of the same kind use, and say what to change it to. **Group repeated instances of one
underlying problem into a single finding** rather than listing every occurrence.

**State which parts of the document you read.** If you did not reach the end, say so plainly. And
write that line as a statement about what you read rather than as a guarantee about what you found,
because two careful passes over one document surface different problems.

Write for the person holding the document. Do not name the file parts, the XML or your own method
in the report; they cannot act on any of it. This matters most when something went wrong, because
"I could not open this document, so nothing here was checked" tells a reader what happened and what
to do next, where a sentence about parsing tells them nothing.