SISYF — Skill Specification#

Note

This is a specification document, not executable code. It defines what SISYF 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 5D link naming architecture.

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

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

1. Purpose #

SISYF reads PoR (Place of Reasoning) 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 #

sisyf <command> [options]

Commands: replace, append, archive, migrate

Options:
  --topics <list>              Default: all
  --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. - 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)
`-`	Omit entirely (field does not appear at this depth)
`stub`	Heading only, marked `[stub --- content pending]`
`link`	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	link	full
3	`name`	ExplicitName	full	-	-	full	full
4	`sum`	SummarizingName	full	full	rewrite	brief	full
5	`intro`	ExplanationIntroOverview	full	rewrite	rewrite	-	-
6	`latex`	FormalMathLatex	full	brief	-	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	-	full	-
8	`tcnt`	TechExplanationContentAll	full	-	-	full	-
9	`logic`	LogicsUsed	full	-	-	full	full
10	`twhy`	TechReasoningAll	full	-	-	full	-
11	`tinf`	TechInformal	full	full	rewrite	-	-
19	`limit`	Limit	full	brief	-	full	link
30	`needs`	NeedsFeed	full	-	-	full	full
31	`feeds`	FeedsNeed	full	-	-	full	full
32	`stayc`	StabilityCode	full	link	-	link	full
33	`mento`	MentorOrganizing	stub	-	-	-	-
34	`diff`	VersioningHistory	stub	-	-	-	-
36	`con`	ConsRef	full	link	-	link	link
37	`pro`	ProsRef	full	link	-	link	link
39	`vvnow`	VersionedVariantCurrent	full	link	-	link	full
40	`model`	ModelUsedIn	full	full	full	full	full
41	`conv`	Convergence	full	brief	rewrite	-	-
42	`bib`	Bibliography	full	top3	-	link	link
43	`pol`	Policy	stub	-	-	-	-
44	`his`	History	stub	-	-	-	-
45	`doi`	DOI	stub	-	-	-	-

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

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

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

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

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	-	-
47	`vchr`	ViewChristianity	full	top3	top1	-	-
48	`visl`	ViewIslam	full	top3	top1	-	-
49	`vhin`	ViewHinduism	full	top3	top1	-	-
50	`vbud`	ViewBuddhism	full	top3	top1	-	-
51	`lde`	CulturalGerman	full	-	-	-	-
52	`lar`	CulturalArabic	full	-	-	-	-
53	`lhe`	CulturalHebrew	full	-	-	-	-
54	`lzh`	CulturalChinese	full	-	-	-	-

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	link	stub	-
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

3.8 Synthesis Pages #

A synthesis page combines content from multiple PoR source fields into a single output page. Unlike the default 1:1 mapping (one field → one output), a synthesis page draws from two or more fields and presents a curated selection.

Naming convention: Synthesis page filenames must differ from all extraction matrix keywords (stor, sheb, sgos, etc.). Keyword names are reserved for 1:1 field mappings. Thematic names signal that the page is a curated synthesis.

Defined synthesis pages:

Page name	Source fields	Content
`hebrew-bible`	`stor` + `sheb`	Torah and Hebrew Bible citations combined. Best quote highlighted per axiom; full listing in dropdown.
`gospels-apostles`	`sgos` + `sapo`	Gospels and Apostolic citations combined. Same pattern: best quote highlighted, full listing in dropdown.
`quran-based`	`squr` + `stor` + `sgos`	Quran citations listing also Torah and Gospel citations, because the Quran recognizes both as inspired. Best quote from the Quran is highlighted; the dropdown groups all three sources.

Rendering rules for synthesis pages:

For each axiom, select the single strongest citation across all source fields as the highlighted quote.
List all citations from all source fields in a collapsible dropdown, grouped by source field with bold labels (e.g., Torah (stor): …, Hebrew Bible (sheb): …).
The page intro (.. compiler:protected-section) is human-crafted and preserved across recompiles.

4. Modes #

4.1 REPLACE Mode #

Regenerate ALL downstream pages from current PoR sources.

When to use: PoR content has changed substantially.

Execution sequence:

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
Parse each element (axiom, theorem, quest entry) into its PoR fields. Each element is identified by its .. _label: directive.
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.
Rebuild toctree directives in all affected index.rst files.
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:

Read all PoR source files.
Diff against existing output folder to identify NEW elements (elements with no corresponding output page).
Generate pages for new elements only (same extraction logic as REPLACE).
Add new entries to existing toctree directives.
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:

Run REPLACE first (ensure all downstream pages are current).
Copy entire output folder to vv/{version}/.
Tag all labels with version suffix (e.g., pet-ax5-oov2r0).
Update version registry in the AHA design document.
If --freeze-por yes: copy PoR source files to per-model VV archives.
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:

Read old-format files.
Build a migration table mapping old labels to new labels.
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
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 SISYF 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 id field for the element number prefix (e.g., a5 not ax5), followed by the title’s descriptive part. This reserves the human’s right to finalize display titles independently. The id field is always lowercase per BEST Names grammar.
Math: prefix with “Formal: “ (e.g., “Formal: 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 Pre-Write Protection Check #

Before writing to any file that already exists on disk, the compiler must check whether the file begins with the .. compiler:protected comment token. If the token is present, the compiler must:

Skip the file (do not write, modify, or delete it).
Log a notice: SKIP [protected]: {path}
Continue to the next file without error.

This check applies to all modes (replace, append, archive, migrate). It is the machine-enforceable form of DD-b12 Rule 6. The token is an RST comment and is invisible in rendered HTML.

Pseudocode#

if target_path.exists():
    first_line = target_path.read_text().lstrip().split('\n')[0]
    if first_line.startswith('.. compiler:protected'):
        log(f'SKIP [protected]: {target_path}')
        return  # do not write

9.2 Protected Sections Within Compiled Pages #

Some compiled pages contain human-crafted sections that must survive regeneration (e.g., a hand-edited intro on an otherwise compiled page). These sections are marked with start/end comment tokens:

.. compiler:protected-section start
   Human-crafted intro. The compiler preserves this section verbatim
   during regeneration.

[human-crafted content here]

.. compiler:protected-section end

When the compiler regenerates a page that contains these markers, it must:

Extract the content between start and end markers.
Regenerate the rest of the page normally.
Re-insert the preserved content at the same position.

If no markers are found, the entire page is regenerated. This is distinct from .. compiler:protected (Section 9.1), which protects an entire file. Protected sections protect a region within an otherwise compiled file.

9.3 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.3.1 LaTeX Math Block Preservation #

When extracting and emitting latex fields (.. math:: blocks), the compiler must preserve the exact whitespace and LaTeX formatting from the PoR source, including:

\\ (LaTeX line-break markers)
& (alignment markers, used with \\ for multi-line alignment)
\bigl, \bigr, \Bigl, \Bigr (bracket sizing)
Indentation within the math block

RST’s .. math:: directive ignores RST-level line breaks. Multiple RST lines within a math block are concatenated into a single LaTeX expression unless the source contains explicit \\ markers. If the compiler strips or fails to copy these markers, multi-line formulas collapse into a single overflowing line in the rendered output.

Rule: Copy the entire content of each .. math:: block character-for-character from the PoR source. Do not reflow, rewrap, or normalize whitespace within math blocks.

9.4 Cross-Reference Integrity #

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

Collect all labels defined in generated pages
Collect all :ref: targets used in generated pages
Check that every target either exists in generated pages or in the source PoR files
Report any orphaned references as warnings

9.5 Toctree Management #

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

Read the existing index.rst
Add new entries in alphabetical order within the appropriate section
Never remove existing manually-created entries
Mark auto-generated toctree sections with a comment: .. Auto-generated by SISYF. Do not edit below.