reference-authoring

name	reference-authoring
metadata	{"internal":true}
description	Authoring discipline for new AZIMUTH reference files and templates. Use when adding a new domain reference file, extending an existing one, or creating a new template. Covers: (1) EXTEND vs. CREATE decision heuristic, (2) the Module 7 vocabulary header pattern that prevents domain-gap recurrence, (3) the sourcing caveat pattern for narrow-evidence-base files, (4) pre-verdict gate structure for templates. Validated by research-mpbaese4 (2026-05-18).
author	Claude Sonnet 4.6
version	1.0.0
date	"2026-05-18T00:00:00.000Z"

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.

Sourcing Caveat Pattern

Include a sourcing note near the top of any reference file where the evidence base is narrower than software-failure-patterns.md or ma-partnership-patterns.md.

Include when:

• Primary source is a single study or report (even a large one)
• Methodology of the primary source is undisclosed
• Evidence base has not been replicated across multiple independent sources

Format:

**Sourcing note:** Pattern rates below are drawn primarily from [Source] ([year],
N=[sample], [methodology caveat if applicable]). Treat percentage rates as
directional, not precise. Evidence base is narrower than [comparator file].

Example: hiring-failure-patterns.md draws primarily from Leadership IQ 2011 (N=5,247, methodology undisclosed) and Schmidt & Hunter 1998. Rates cited as directional accordingly.

Pre-Verdict Gate Structure (Templates)

Use explicit blocking gates — not just checkboxes — when a pattern is structurally impossible to surface without a structured diagnostic section.

Signal that a gate is needed: The failure pattern requires specific arithmetic (runway scenarios), a governance checklist (co-founder structure), or a concentration threshold (>40% customer share) that cannot be expressed as prose.

Gate structure:

1. Run the gate before the verdict section (not after)
2. State the blocking condition explicitly: "Any PENDING item blocks PROCEED verdict"
3. Include the specific threshold or criterion inline, not as a footnote

Example gates validated this session:

• PMF Validation Gate — 3+ behavioral YES required; absent PMF locks confidence ceiling at LOW and blocks PROCEED/PROCEED WITH SAFEGUARDS
• Runway Scenario Table — three rows: base / optimistic (+40% revenue) / pessimistic (−40% revenue, +20% burn); < 6 months in pessimistic = hard block
• Co-Founder Structure Check — any PENDING item blocks PROCEED regardless of other findings

Distinguish gates from checklists: gates have explicit verdict consequences stated in the gate itself. Checklists surface information; gates block verdicts.

Validation After Authoring

Run these checks before committing any new reference file or template:

# 1. All paths referenced in SKILL.md must exist
grep -oE '(references|diagnostics|templates)/[^ \n"`]+\.md' SKILL.md | sort -u | \
  while read f; do test -f "$f" && echo "OK: $f" || echo "MISSING: $f"; done

# 2. SKILL.md frontmatter description must remain 489 chars
awk '/^description: /{flag=1} flag{print; if(/"$/) flag=0}' SKILL.md | tr -d '\n' | wc -c

# 3. gotchas.md must still have exactly 8 numbered sections
grep -E '^## [0-9]+\.' gotchas.md | wc -l

Notes

• The Module 7 vocabulary header is the main architectural defense against gap recurrence. If a new domain is added without this header, the gap scanner will catch the symptom (Module 7 producing generic output) but not the cause.
• EXTEND operations require no SKILL.md changes if the domain is already in the DEEP mode load rules. Migration patterns required no SKILL.md change; hiring required one line added to the DEEP mode domain reference block.
• Reference file pattern format: ## Pattern N: [Title] / **What happens**: / **Failure signature**: (bullet list) / **Azimuth question**:. Match density and register of software-failure-patterns.md exactly.