---
name: defined_terms_audit
description: Audit every defined term in a contract against the whole document, schedules included: defined but unused, used but undefined, used before it is defined, defined twice, and used in a different case or written form, with variant forms checked before anything is called missing and a completeness note that says what was actually read. Ships a tested term extraction and variant matching script plus a worked contract with planted defects. Use when a contract, agreement, or terms document needs a definitions check before signing, when schedules or exhibits were drafted separately, or when a term seems to shift meaning between sections.
---

# Defined Terms Audit

## Purpose

Check a contract's private vocabulary against itself. A defined term is a promise: this label means this one thing, everywhere in this document. The audit finds where that promise breaks. A term is defined and never used. A term carries duties and deadlines and is never defined. A term is defined twice, in the body and again in a schedule, with wordings that do not quite match. A term is used for six sections before its inline definition shows up. A term is written lowercase or hyphenated in one place, which raises the question whether the defined meaning was meant there at all.

These are meaning defects, not style nits. Practitioners name defined but unused and used inconsistently as the most common defined term mistake (Gibbes Burton, "Use Defined Terms Properly in Your Next Contract"). Courts faced with inconsistent terms try to reconcile them, favouring the specific term over the general one, and only rule a term ineffective as a last resort (BG Checo International v British Columbia Hydro [1993] 1 SCR 12). An unused definition is not safe either: in Rayford Homes v Bank of Scotland [2011] the court gave an unused definition a meaning drawn from the purpose of the contract. This is a drafting audit, not legal advice on a live deal.

This skill ships three things. Use all three:

- The audit script: `scripts/audit_defined_terms.py`, standard library only.
- A worked contract with 10 planted defects and a scored answer key: `references/worked-contract.md` and `references/answer-key.md`.
- A report template: `assets/report-template.md`.

A general clause review is a different job. This skill covers defined terms only, across the whole document set, and says exactly what it read.

## Workflow

1. **Assemble the whole document set before reading anything.** Collect the main body plus every schedule, exhibit, annex, appendix, and amendment, and any side letter that defines or uses terms. Schedules are incorporated into the agreement and form part of it, so a term defined only in a schedule counts as defined, and a term used only in a schedule counts as used. Put the files in document order: body first, attachments after. Convert docx or PDF files to plain text or markdown first and keep the conversion faithful, one paragraph per line where you can. Scanned pages need OCR before they can be audited at all. If a part cannot be obtained, name it in the completeness note and keep auditing what you have. Never audit the body alone and call it the whole contract.

2. **Run the script.** From this skill's folder: `python3 scripts/audit_defined_terms.py BODY.txt SCHEDULE1.txt SCHEDULE2.txt --json report.json`, listing every file in document order. Exit 0 means no findings in what was read, exit 1 means findings, exit 2 means a file could not be read. The script extracts definitions in the three standard shapes (a quoted term followed by means or includes, and a quoted term in parentheses after the thing it names), then searches every use in every variant form before it calls anything missing: exact, plural, singular, possessive, hyphenated, spaced, and different letter case.

3. **Add aliases and rerun before trusting a missing verdict.** The script cannot know that a document shortens a term to an acronym or a nickname of its own. Read the definitions once yourself, note every short form the document actually uses, and rerun with one flag per term, for example `--alias "Confidential Information=CI"`. A term may only be reported as unused after the alias pass. The same applies in reverse: if the script flags a use count that looks too high, check whether a variant form is catching part of a longer different term, and say so in the report rather than quietly adjusting the number.

4. **Confirm each used but undefined candidate by hand.** The script lists repeated Title Case phrases with no definition and labels them candidates. For each one, read the sentences it appears in. Confirm it if it carries duties, deadlines, money, or scope. Clear it, with the reason recorded, if it is a party or product name, a heading, an ordinary Title Case phrase, or a term defined in a document incorporated by reference. If that incorporated document exists, get it and rerun the audit with it included before calling the term undefined. Single word undefined terms do not surface this way, so scan the operative clauses once yourself for capitalised single words that do real work.

5. **Sort confirmed findings by the harm they can do.** Used but undefined in an operative clause and duplicate definitions come first, because both leave meaning open in a dispute, and a duplicate with no precedence clause leaves two meanings open. Used before defined comes next, for inline definitions only: the script treats definitions in a definitions section and in schedules as available from the start, by the usual document convention, and says so in its output. Defined but unused follows: the fix is to delete the definition or use the term on purpose, never to leave it in by default. Case and form variants follow: capitalisation is the signal that a defined meaning is meant, so a lowercase or rehyphenated use asks a real question, but read the sentence before calling it an error, because the writer may have meant the ordinary word. Defined but barely used is a warning, not a finding: a term used once has to earn its definition, and where plain words would do the same job, the definition is cost without benefit.

6. **Check the interpretation clauses against the findings.** The script reports whether the document states that the singular includes the plural and the plural includes the singular. If that rule is absent, every singular against plural mismatch in the findings goes up one level of concern, because nothing in the document resolves it. Also check, by reading, whether the document has a precedence clause covering the body against its schedules. If it has none and there is a duplicate definition across body and schedule, say plainly that the document itself does not say which wording wins.

7. **Give each confirmed finding one fix.** Define the undefined term, with any wording you propose marked as a proposal for the document owner or their lawyer to settle. Delete the unused definition, or add the missing use where the concept was meant to apply. Keep one duplicate definition and make the other place point at it. Move an inline definition that is used early into the definitions section. Align every case and form variant to the defined form, or change the definition to the form the document actually uses and align to that. Apply fixes to a copy, rerun the audit on the fixed copy, and report the new counts next to the old ones.

8. **Write the completeness note first in the report, not last.** Copy the file list and line counts from the script output, add anything you skipped or could not read by name, and word the verdict to match the scope: "no findings in the body and two schedules listed above" is allowed, "the contract is clean" is not. Fill in `assets/report-template.md` for the rest of the report.

9. **Verify the tool when the stakes justify it.** Run `python3 tests/score_audit.py` from this skill's folder. Expected result: 10 of 10 planted findings on the worked contract, no extras, no warnings, and the clean contract at `tests/clean-contract.md` clear with exit 0. Do this before trusting the script on a new Python version or after editing it, and read `references/answer-key.md` once before your first real audit so you know what each finding kind looks like when it is real.

## Output Contract

- Completeness note: every file read with its line count, the defined term count, whether the singular and plural rule was found and where, and a named list of what was not read.
- Findings grouped by kind, worst first: used but undefined, duplicate definitions, used before defined, defined but unused, case and form variants, then barely used warnings.
- Each finding: the term, the kind, the definition location and every use location as file and line, one short quoted sentence as evidence, and the one recommended fix.
- A candidates cleared list: each Title Case candidate the script raised and the report cleared, with the reason in one line. Cleared candidates stay visible so the next reader does not raise them again.
- A per-term count list: term, where defined (definitions section, inline, or schedule), total uses, and how many uses were in variant forms.
- Counts that add up: findings by kind from the script, split into confirmed, cleared, and warnings, summing to the same totals after the alias rerun and any fixes.

## Operating Rules

- Read the whole set or say what is missing. A definitions audit of part of a contract is a partial audit, and the report must read that way.
- Variants before verdicts. No term is called unused or missing until plural, singular, possessive, hyphenated, spaced, case, and known alias forms have all been searched.
- Candidates are not findings. A repeated Title Case phrase becomes a finding only after a person reads its sentences and confirms it is doing defined term work.
- One fault, one count. A single sloppy sentence can produce a case finding for three terms. Report the sentence once as the fix target and list the terms under it.
- Do not invent a definition and present it as the document's intent. Proposed wording is marked as a proposal, every time.
- Do not fix by global search and replace. The same string can be a defined term in one sentence and an ordinary word in the next. Fix per finding, with the sentence in view.
- Quote evidence. Every finding carries at least one real line from the document, so the owner can find the spot and judge the call without rerunning anything.
- Keep the report in plain sentences, short locations, and real counts. No em dashes.