AHA: SISYF User Guide#

Note

Status: SISYF is specified but not yet implemented as executable code. This guide documents how it will work based on the specification at SISYF — Skill Specification. Phase 2I-4 performs the first manual compilation run following this spec.

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

1. Quickstart #

“I just want to see it work.” The three most common operations:

1.1 Generate expert + easy views for all axioms #

sisyf replace --depths expert,easy --output matheology/

This reads all PoR sources (pet/axioms.rst, jub/axioms.rst, jub/theorems.rst), applies the extraction matrix, and writes one RST page per element per depth into topic subdirectories (e.g., axioms/easy/, axioms/expert/). See DD-b12 for why output lives here, not in a separate compiled/ folder.

Expert pages: All 32 non-stub fields copied verbatim from PoR. 13 stub fields shown as [stub --- content pending] headings.
Easy pages: Simplified titles, rewritten intros, single strongest citation per tradition. Technical fields omitted.

1.2 Add a new model without regenerating existing pages #

sisyf append --models 4be

Only elements from model 4be that do not yet exist in the output folder are generated. Existing PET and JUB pages are untouched.

1.3 Freeze the current state as a versioned archive #

sisyf archive \
  --version-increment r \
  --vvn hv_LLoL_OOv2r1p0_2026m04d01 \
  --stayc QQ

Runs REPLACE first, then copies everything to vv/OOv2r1p0/ with version-suffixed labels. Use this at major milestones.

2. Concepts #

2.1 The 5D Namespace #

Every element in the matheology lives in a 5-dimensional label space. The compiler operates across all 5 dimensions:

D	Dimension	Examples	What the compiler does with it
D1	Model	`pet`, `jub`	`--models` selects which model sources to read
D2	Type ID	`ax5`, `th1`, `con9`	Determines which elements get compiled
D3	Version	`oov2r0`	`--version-increment` for archive mode
D4	Depth (Audience)	`easy`, `prod`, `math`, `ma`	`--depths` selects which views to generate
D5	View/Source/Language	`vjud`, `stor`, `lde`	`--views` selects which tradition fields to include

The full architecture is defined in 5D link naming architecture.

2.2 The Extraction Matrix #

The extraction matrix is a table with 54 rows (PoR fields) and 5 columns (audience depths). Each cell tells the compiler how to handle that field at that depth:

Keyword	What happens
`full`	Field copied verbatim from PoR source
`brief`	First sentence only
`top3`	Top 3 entries from a list
`top1`	Single strongest entry
`drop`	Field omitted entirely — does not appear on the page
`stub`	Heading appears, body says `[stub --- content pending]`
`ref`	Cross-reference link to the expert PoR page
`rewrite`	Content rewritten for the target audience (flagged for human review)

The full matrix is in SISYF — Skill Specification Section 3.

2.3 Depth Profiles at a Glance #

What each audience actually sees:

Expert (default): Everything. The full PoR with all 45 fields. 13 stub fields shown as scaffolding for future content.
Producer (prod): Identity fields, rewritten intro, brief technical context, top 3 source citations per tradition. No POST fields, no machine data. 25 fields total.
Easy: Simplified titles, plain-English intro, informal intuition, convergence across traditions, single strongest citation per tradition. 13 fields total.
Math (math): LaTeX, logic, full technical reasoning, dependency graph, limitations. No sources, no prose. 19 fields.
Machine (ma): Structured identifiers, LaTeX, logic, dependency graph, stability code, version info. No prose. 15 fields.

3. Reference #

3.1 Modes #

Mode	What it does
`replace`	Regenerate ALL downstream pages from current PoR sources. Use when PoR content has changed substantially.
`append`	Generate pages for NEW elements only (elements not yet in output). Use when adding a new model or new axioms.
`archive`	Run `replace` first, then copy to a versioned archive folder. Tags all labels with version suffix. Use at major milestones.
`migrate`	Transform existing files from one naming convention to another. Use after structural changes (e.g., `ax1` to `pet-ax1`).

3.2 All Options #

Option	Default	Notes
`[mode]` (positional)	(required)	`replace`, `append`, `archive`, `migrate`
`--output <folder>`	`matheology/`	Where compiled pages are written
`--models <list>`	`all`	Comma-separated: `pet`, `jub`, `4be`, or `all`
`--depths <list>`	`all`	`expert`, `prod`, `easy`, `math`, `ma`, or `all`
`--views <list>`	`all`	Which D5 tradition codes to include (`vjud`, `stor`, etc.)
`--states <list>`	`all`	Which D2 type IDs to compile pages for
`--stubs yes\|no`	`no`	When `no`: pages that would be entirely stubs are not generated
`--version-increment <v\|r\|p>`	(archive only)	`v` = incompatible, `r` = features, `p` = bugfix
`--archive-folder <path>`	`vv/{version}/`	Where the archive copy is written
`--vvn <string>`	(archive only)	Versioned Variant Number, e.g., `hv_LLoL_OOv2r0p0_2026m03d22`
`--stayc <code>`	(archive only)	StayVS maturity code for the compilation
`--freeze-por yes\|no`	`no`	Copy PoR source files to per-model VV archives

3.3 What the Compiler Reads #

The compiler needs these source files:

source/matheology/pet/axioms.rst        (ax1--ax14)
source/matheology/jub/axioms.rst        (ax15--ax25)
source/matheology/jub/theorems.rst      (th1--th11)
source/matheology/jub/quest.rst         (con/pro entries)

Plus these operational references in compiler/sisyf/ww/:

compiler/sisyf/ww/sisyf-skill.rst                (extraction matrix + modes)
compiler/space/ww/5d-link-naming-matheology-aha.rst (5D label grammar)
compiler/sisyf/ww/stubs/matheology-*.rst         (5 stub templates)

3.4 What the Compiler Writes #

For replace mode with --depths expert,easy:

source/matheology/axioms/expert/
source/matheology/axioms/easy/

The compiler writes into depth subdirectories beneath topic-level landing pages. It never overwrites index.rst files (which are human-crafted). See DD-b12 for the full input/output boundary rules.

Labels follow the BEST Names grammar: pet-ax5 (expert), pet-ax5-easy (easy), pet-ax5-math (math), etc.

4. Stub Templates #

Five stub templates exist at compiler/sisyf/ww/stubs/:

Template	Fields	Purpose
`matheology-expert.rst`	54	Full scaffold — every field as a heading. Shows the complete intended structure even before content exists.
`matheology-producer.rst`	25	Teaching/preaching scaffold. Identity, intro, sources (top 3), convergence, key traps (KnownKiller).
`matheology-easy.rst`	13	Beginner scaffold. Plain titles, informal intuition, single strongest citation per tradition.
`matheology-math.rst`	19	Formal scaffold. LaTeX, logic, reasoning, dependencies, limitations, bibliography.
`matheology-machine.rst`	15	API scaffold. Identifiers, LaTeX, logic, dependency graph, stability code, version info.

When to use ``–stubs yes``: Generate stub pages when you want to see the full intended page structure as scaffolding for a research round. The stubs show which fields need content. Each stub heading says [stub --- content pending] — an explicit invitation to fill it in.

When to use ``–stubs no`` (default): For any output that readers will see. Prevents empty pages and dead links.

5. Troubleshooting #

5.1 Duplicate-label warnings after copying files #

Symptom: Sphinx warns about duplicate labels after files are copied to a new location.

Cause: RST labels are globally unique. If a file is copied without renaming its labels, both copies define the same label.

Fix: The compiler/sisyf/ww/ copies use compiler- prefixed labels (e.g., compiler-5d-link-naming instead of aha-best-names-matheology). If you copy any file from vv/ to compiler/, rename all .. _label: directives and update all :ref:`label` references in the copy.

5.2 “Undefined label” warning from the skill spec #

Symptom: WARNING: undefined label: 'aha-best-names-for-matheology-links'

Cause: The label in the AHA doc is aha-best-names-matheology (short form), not the full filename. This was caught during Phase 2I-3.

Fix: Use the correct label. In the compiler/sisyf/ww/ copy, the label is compiler-5d-link-naming.

5.3 Token budget exceeded #

Symptom: Claude Code runs out of context mid-session.

Cause: Reading the full AHA doc (~32K tokens) + full quest.rst (~48K tokens) + full debug llog (~37K tokens) exhausts the 200K window.

Fix: Use selective reads. The prompts in this series specify which sections to read with line-range hints. For the AHA doc, Sections 7, 9, 10, and 12 contain what the compiler needs (~25K tokens vs. ~32K for the full file). For quest.rst, grep for specific citations rather than reading in full.

5.4 Toctree warnings for stub templates #

Symptom: WARNING: document isn't included in any toctree for stub template files.

Cause: Stub templates are templates (used by the compiler at generation time), not content pages. They are not meant to be in a toctree.

Non-issue: These warnings are expected and harmless. The templates in compiler/sisyf/ww/stubs/ are included in the compiler’s toctree specifically to suppress this warning. The copies in _templates/stubs/ may still warn — this is acceptable.

6. Maintenance: Keeping `/compiler/` Current #

6.1 What lives where #

Location	Role
`compiler/sisyf/ww/`	Living working copies. Edit these. The compiler reads from here.
`compiler/aha/`	This user guide. Update when behavior changes.
`vv/jub/oov2/llog/`	Frozen audit trail. Never edit. These are the Phase 2I-3 originals, preserved for the historical record.
`_templates/stubs/`	Sphinx template copies. Keep in sync with `compiler/sisyf/ww/stubs/` if the stub format changes.

6.2 Remaining 2I prompts that affect the compiler #

Prompt	Phase	What it should update in `compiler/`
2I-4	First Compilation Run	The first real output. Read skill spec and stubs from `compiler/sisyf/ww/`, not from `vv/jub/oov2/llog/`. Output goes to topic subdirectories under `source/matheology/` (e.g., `axioms/easy/`), per DD-b12. After the run, update this AHA guide with any lessons learned.
2I-6	Public Documentation	Reads the AHA doc. Should read from `compiler/sisyf/ww/` instead of `vv/jub/oov2/llog/`. May produce pages that should be added to `compiler/aha/` or cross-referenced from it.
2I-7a	Deliverable Audit	Must include `compiler/` in its audit scope. Check that `ww/` files are consistent with the `vv/` originals (labels renamed, content otherwise identical).
2I-7b	Closing Llog	Document the `compiler/` directory in the closing record. Note that it is the canonical home for the skill going forward.

6.3 Prompt path updates needed #

The following prompt files still reference vv/jub/oov2/llog/ paths for files that now live in compiler/sisyf/ww/. Before executing these prompts, update the file references or prepend an instruction telling the session to read from compiler/sisyf/ww/ instead:

prompt_2I-4.rst lines 51–54: AHA doc and skill spec paths
prompt_2I-4.rst lines 74–79: stub template paths
prompt_2I-6.rst line 33: AHA doc path
prompt_2I-7b.rst line 37: AHA doc path

6.4 When to update the extraction matrix #

Update the matrix in compiler/sisyf/ww/sisyf-skill.rst (Sections 3.2–3.6) when:

A new PoR field is added (add a row)
A new audience depth is added (add a column)
Field testing reveals a field has moved from >50% stub to <50% stub (change stub to full at expert depth)
User feedback indicates a field should be visible at a depth where it was previously drop

After any matrix change, re-run replace to regenerate all pages.

6.5 When to update the 5D architecture doc #

Update compiler/space/ww/5d-link-naming-matheology-aha.rst when:

A new D1 model is registered (e.g., 4be)
A new D2 type ID is created
A new D4 depth is added
A new D5 view, source, or language code is registered
The label grammar rules change

The compiler/sisyf/ww/ copy is the living version. The vv/jub/oov2/llog/ copy is frozen history.