reference-authoring

Reference File Authoring Discipline

Problem

Each new domain addition to AZIMUTH risks leaving Module 7 without vocabulary for the new domain — or creating redundant files when extension was the right operation. The symptoms: Module 7 produces generic output for a domain, or the analyst must load two files to complete one domain analysis.

EXTEND vs. CREATE Decision

EXTEND an existing file when:

• Adding ≤ 3 new patterns (≤ 30% increase on a 10-pattern file)
• The majority of existing patterns already apply to the new domain
• The file's own load condition already covers the new domain

CREATE a new file when:

• Adding 6+ patterns that are distinct from the existing file
• The new domain requires different load conditions than the host file
• Loading both the existing file and new content would require two separate loads anyway

Example applied: Migration patterns (3 patterns, 9 of 10 existing patterns apply to migrations) → EXTEND software-failure-patterns.md. Hiring patterns (6 patterns, zero overlap with software failure modes) → CREATE hiring-failure-patterns.md.

At 4–5 patterns, use judgment: if the domain is structurally distinct and all patterns are domain-specific (not shared with the host file), CREATE. If the domain shares most of its mechanisms with the host file, EXTEND.

Module 7 Vocabulary Header

Every new reference file and template must answer this question in its header:

"What vocabulary and diagnostic anchors does this file supply to Module 7?"

Without this, each new domain leaves Module 7 producing generic output — the analyst gets no domain-specific signal even when the file is loaded.

Format (include near the top of the file, after the load condition):

**Module 7 vocabulary this file supplies:** [list of specific terms, base rates,
and diagnostic anchors — e.g., "coachability as a distinct failure mode (26% of
failures); interpersonal vs. technical failure rate inversion (81% vs. 11%)"]

Why it matters: The gap scanner found that the hiring and startup domains both hit the same failure — Module 7 expected template-supplied domain vocabulary that wasn't there. The Module 7 header makes this provision explicit and checkable.