/compile-matheology — Compilation Skill Definition

Note

This is a specification document, not executable code. It defines what the /compile-matheology skill should do so that a future Claude Code session can implement it as an actual skill. The authoritative source for field definitions, depth codes, and label grammar is Links for Matheology BEST Names Design.

Created: Phase 2I-3 (2026-03-25).

Prerequisite knowledge: AHA design doc Sections 7, 9, 10, 12.

---

1. Purpose

The /compile-matheology skill reads PoR (Point of Research) source files and generates audience-specific downstream pages using the Extraction Matrix defined in Section 3 below. Each generated page contains only the fields appropriate for its target audience (D4 depth), extracted and transformed according to the matrix keywords.

---

2. Invocation

/compile-matheology [mode] [options]

Modes: replace, append, archive, migrate

Options:
  --output <folder>            Default: matheology/axioms/
  --models <list>              Default: all
  --depths <list>              Default: all
  --views <list>               Default: all
  --states <list>              Default: all
  --stubs yes|no               Default: no
  --version-increment <v|r|p>  Required for archive mode
  --archive-folder <path>      Default: vv/{version}/
  --vvn <string>               Required for archive mode
  --stayc <code>               Required for archive mode
  --freeze-por yes|no          Default: no

---

3. Extraction Matrix

The Extraction Matrix controls which PoR fields appear at each D4 audience depth and how they are transformed. Each cell contains one of the extraction keywords defined below. drop means the field is silently omitted at that depth.

3.1 Keyword Vocabulary

Keyword	Meaning
full	Include in full (field copied verbatim from PoR)
brief	First sentence only (truncate to opening statement)
top3	Top 3 entries (for lists, pick highest-impact items)
top1	Single best entry (e.g., 1 strongest tradition quote)
drop	Omit entirely (field does not appear at this depth)
stub	Heading only, marked [stub --- content pending]
ref	Cross-reference link only (point to PoR for full content)
rewrite	Include, rewritten for audience (rephrase for accessibility or formality)

3.2 Identity & Display (fields 1–6)

#	Brief	Field	Expert	Producer	Easy	Math	Machine
1	id	BriefName	full	full	full	full	full
2	title	Title	full	full	rewrite	ref	full
3	name	ExplicitName	full	drop	drop	full	full
4	sum	SummarizingName	full	full	rewrite	brief	full
5	intro	ExplanationIntroOverview	full	rewrite	rewrite	drop	drop
6	latex	FormalMathLatex	full	brief	drop	full	full

3.3 Technical, Structural, and Analytical (fields 7–11, 19, 30–45)

Fields marked stub at expert depth are >50% stub across all 32 elements per the Phase 2I-2 field testing report.

#	Brief	Field	Expert	Producer	Easy	Math	Machine
7	tctx	TechExplanationContext	full	brief	drop	full	drop
8	tcnt	TechExplanationContentAll	full	drop	drop	full	drop
9	logic	LogicsUsed	full	drop	drop	full	full
10	twhy	TechReasoningAll	full	drop	drop	full	drop
11	tinf	TechInformal	full	full	rewrite	drop	drop
19	limit	Limit	full	brief	drop	full	ref
30	needs	NeedsFeed	full	drop	drop	full	full
31	feeds	FeedsNeed	full	drop	drop	full	full
32	stayc	StabilityCode	full	ref	drop	ref	full
33	mento	MentorOrganizing	stub	drop	drop	drop	drop
34	diff	VersioningHistory	stub	drop	drop	drop	drop
36	con	ConsRef	full	ref	drop	ref	ref
37	pro	ProsRef	full	ref	drop	ref	ref
39	vvnow	VersionedVariantCurrent	full	ref	drop	ref	full
40	model	ModelUsedIn	full	full	full	full	full
41	conv	Convergence	full	brief	rewrite	drop	drop
42	bib	Bibliography	full	top3	drop	ref	ref
43	pol	Policy	stub	drop	drop	drop	drop
44	his	History	stub	drop	drop	drop	drop
45	doi	DOI	stub	drop	drop	drop	drop

3.4 POST Operational (fields 20–29, 35, 38)

#	Brief	Field	Expert	Producer	Easy	Math	Machine
20	jj	JammedJob	stub	drop	drop	drop	drop
21	aa	AnyAim	stub	drop	drop	drop	drop
22	kk	KnownKiller	full	brief	drop	ref	drop
23	ff	FeedbackFlow	stub	drop	drop	drop	drop
24	cc	CollectedContent	full	brief	drop	ref	drop
25	dd	DesignDoc	stub	drop	drop	drop	drop
26	gg	GrowthGarden	stub	drop	drop	drop	drop
27	hh	HistoryHeap	stub	drop	drop	drop	drop
28	ww	WorkingWheel	stub	drop	drop	ref	drop
29	yy	YesYet	stub	drop	drop	drop	drop
35	ll	LabLog	full	drop	drop	drop	drop
38	vv	VersionedVariant	full	drop	drop	drop	full

3.5 Independent Support — D5 Core (fields 12–18)

#	Brief	Field	Expert	Producer	Easy	Math	Machine
12	stor	SupportTorah	full	top3	top1	drop	drop
13	sheb	SupportHebrewBible	full	top3	top1	drop	drop
14	sgos	SupportGospels	full	top3	top1	drop	drop
15	sapo	SupportApostolic	full	top3	top1	drop	drop
16	squr	SupportQuran	full	top3	top1	drop	drop
17	ssan	SupportSanskrit	full	top3	top1	drop	drop
18	vsec	ViewSecular	full	top3	top1	drop	drop

3.6 Independent Support — D5 Extended (fields 46–54)

Worldview fields follow the same extraction pattern as the core source fields (12–18). Language-specific cultural fields appear only at expert depth because they carry insights that resist translation.

#	Brief	Field	Expert	Producer	Easy	Math	Machine
46	vjud	ViewJudaism	full	top3	top1	drop	drop
47	vchr	ViewChristianity	full	top3	top1	drop	drop
48	visl	ViewIslam	full	top3	top1	drop	drop
49	vhin	ViewHinduism	full	top3	top1	drop	drop
50	vbud	ViewBuddhism	full	top3	top1	drop	drop
51	lde	CulturalGerman	full	drop	drop	drop	drop
52	lar	CulturalArabic	full	drop	drop	drop	drop
53	lhe	CulturalHebrew	full	drop	drop	drop	drop
54	lzh	CulturalChinese	full	drop	drop	drop	drop

3.7 Summary Statistics

Field counts per depth (45 core fields; D5 extensions 46–54 add to each row):

Depth	full	brief	top3	top1	rewrite	ref	stub	drop
Expert	32	0	0	0	0	0	13	0
Producer	5	6	9	0	2	3	0	20
Easy	2	0	0	7	4	0	0	32
Math	11	1	0	0	0	7	0	26
Machine	14	0	0	0	0	3	0	28

---

4. Modes

4.1 REPLACE Mode

Regenerate ALL downstream pages from current PoR sources.

When to use: PoR content has changed substantially.

Execution sequence:

1. Read all PoR source files:

   • source/matheology/pet/axioms.rst

   • source/matheology/jub/axioms.rst

   • source/matheology/jub/theorems.rst

   • source/matheology/jub/quest.rst

2. Parse each element (axiom, theorem, quest entry) into its PoR fields. Each element is identified by its .. _label: directive.

3. For each element x depth x view combination:

   1. Look up the element’s fields in the Extraction Matrix.

   2. For each field, apply the extraction keyword:

      • full: copy field content verbatim

      • brief: extract first sentence (up to first . or \n\n)

      • top3: for list fields, take the first 3 items

      • top1: for list fields, take the first item

      • drop: skip entirely

      • stub: emit heading with [stub --- content pending]

      • ref: emit :ref:`{label}` cross-reference link

      • rewrite: transform prose for target audience (see Section 6)

   3. Generate an RST page using the output template (Section 5).

   4. Write to the output folder using the BEST Names label as filename.

4. Rebuild toctree directives in all affected index.rst files.

5. Run make html to check for warnings or broken references.

4.2 APPEND Mode

Add new elements without regenerating existing entries.

When to use: New model or new elements added (e.g., 4Be model).

Execution sequence:

1. Read all PoR source files.

2. Diff against existing output folder to identify NEW elements (elements with no corresponding output page).

3. Generate pages for new elements only (same extraction logic as REPLACE).

4. Add new entries to existing toctree directives.

5. Run make html to check.

4.3 ARCHIVE Mode

Freeze current state to a versioned archive.

When to use: Major milestone (e.g., OOv2 freeze).

Execution sequence:

1. Run REPLACE first (ensure all downstream pages are current).

2. Copy entire output folder to vv/compiled/{version}/.

3. Tag all labels with version suffix (e.g., pet-ax5-oov2r0).

4. Update version registry in the AHA design document.

5. If --freeze-por yes: copy PoR source files to per-model VV archives.

6. Run make html to check.

4.4 MIGRATE Mode

Transform existing files to a new naming or structural convention.

When to use: Structure change (e.g., ax1 to pet-ax1).

Execution sequence:

1. Read old-format files.

2. Build a migration table mapping old labels to new labels.

3. Transform all files:

   1. Rename label directives (.. _{old}: to .. _{new}:)

   2. Update all :ref:`old` cross-references to :ref:`new`

   3. Update all :doc: paths if file locations changed

4. Run make html to check for any remaining broken references.

---

5. Output Template

Each generated page follows this structure:

.. _{label}:

{title}
{title_underline}

.. This page was generated by /compile-matheology on {date}.
.. Source: {source_file}
.. Depth: {depth_code}
.. Do not edit manually. Re-run the skill to regenerate.

{extracted fields per extraction matrix}

Label construction follows the BEST Names grammar from the AHA design document:

• Expert (default): {model}-{typeID} (e.g., pet-ax5)

• Producer: {model}-{typeID}-prod (e.g., pet-ax5-prod)

• Easy: {model}-{typeID}-easy (e.g., pet-ax5-easy)

• Math: {model}-{typeID}-math (e.g., pet-ax5-math)

• Machine: {model}-{typeID}-ma (e.g., pet-ax5-ma)

Title construction:

• Expert: use title field verbatim

• Producer/Easy: use title field, may be rewritten for audience

• Math: prefix with “Formal: “ (e.g., “Formal: ax5_A5 — Human Exceeding”)

• Machine: prefix with “Data: “ (e.g., “Data: pet-ax5”)

---

6. Rewrite Rules

When the extraction keyword is rewrite, the skill transforms the field content for the target audience. The following rules apply:

Producer (PoT) rewrites:

• Remove technical jargon; prefer plain language

• Keep theological precision intact

• Restructure for teaching flow (context before claim)

• Preserve all scripture citations but simplify notation

Easy (PoU) rewrites:

• Use short sentences (target: 15 words average)

• Replace formal notation with natural-language equivalents

• Lead with “In plain English:” style framing

• Use analogies from everyday experience

• Omit citation locators; keep only the quoted text

Rewrite is never automatic. When the skill encounters a rewrite cell, it should flag the field for human review after generation. The generated version is a draft; the human decides whether to accept, edit, or reject it.

---

7. Stub Policy

When ``–stubs no`` (default):

• If an individual field would be stub at a given depth, the heading is included with the [stub --- content pending] marker.

• If an ENTIRE PAGE would contain only stub and drop fields (i.e., no full, brief, top3, top1, rewrite, or ref content), the page is NOT generated and no toctree entry is created. This prevents empty pages.

When ``–stubs yes``:

• All pages are generated regardless of content level.

• Stub-only pages use the depth-appropriate stub template from source/_templates/stubs/matheology-{depth}.rst.

• Stub pages are marked with a visible banner: .. warning:: This page is a stub. Content pending.

---

8. User Decisions Reference

The 13 user decisions from AHA Section 12.2, mapped to CLI options:

#	Decision	CLI option	Default	Notes
1	Mode	[mode] (positional)	(required)	replace, append, archive, migrate
2	Output folder	--output	matheology/	Override for non-standard locations
3	Models to include	--models	all	Comma-separated: pet,jub or all
4	Audience-depths	--depths	all	Comma-separated: expert,prod,easy,math,ma
5	Worldviews	--views	all	Which v-codes and s-codes to generate
6	D2 chain types	--states	all	Which D2 type IDs to generate pages for
7	Stub folder	(hardcoded)	_templates/stubs/	Pre-defined stub templates for depths
8	Generate stubs?	--stubs	no	If no, omit pages that would be entirely stubs
9	Version increment	--version-increment	(required for archive)	v (incompatible), r (features), p (bugfix)
10	Archive folder	--archive-folder	vv/{version}/	Override for non-standard location
11	VVN	--vvn	(required for archive)	e.g., hv_LLoL_OOv2r0p0_2026m03d22
12	StayVS maturity	--stayc	(required for archive)	StayC code for the compilation
13	Freeze PoR?	--freeze-por	no	Copy PoR sources to per-model VV archives

---

9. Implementation Notes

9.1 PoR Field Parsing

The current PoR format (as seen in pet/axioms.rst and jub/axioms.rst) uses a semi-structured RST format:

• Each element starts with .. _{label}:

• Title is the next heading (underlined with ^^^ or ===)

• sum is the first italic line after the title

• intro follows “In plain English:”

• latex is inside .. math:: blocks

• tctx follows “Explanation:”

• Source fields follow “Scriptural and philosophical support:” as a bullet list, keyed by tradition name in bold

The parser must extract these fields by pattern matching against the current RST structure. If the structure changes, the parser must be updated.

9.2 Cross-Reference Integrity

After any compilation run, all :ref: links in generated pages must resolve. The skill should:

1. Collect all labels defined in generated pages

2. Collect all :ref: targets used in generated pages

3. Check that every target either exists in generated pages or in the source PoR files

4. Report any orphaned references as warnings

9.3 Toctree Management

Generated pages must be added to toctree directives in the appropriate index.rst files. The skill should:

1. Read the existing index.rst

2. Add new entries in alphabetical order within the appropriate section

3. Never remove existing manually-created entries

4. Mark auto-generated toctree sections with a comment: .. Auto-generated by /compile-matheology. Do not edit below.

TELES migration report (2026m04d04)

Mechanical identifier migration applied to this file. All axiom/theorem text references were migrated from short form (e.g., A15) to compound form (e.g., ax15_A15) as part of the matheology compound naming operation. Both forms refer to the same formal object. The old form survives as the suffix to ensure consistency with the oldest records; the new form adds a temporary-status prefix. Forward-facing pages use brief form (ax15) only. See TELES Axiom/Theorem Compound Naming — Execution Prompt for the complete mapping table and DD b12 — Legacy Naming for PET/JUB Axioms and Theorems for the permanent reference.