AA: SISYF Implementation Tasks#

Created: Phase 2I-4 (2026-03-25)

Problem: The compiled expert page (axioms/expert/index.rst) was hand-edited during Phase 2I-4 to make it presentable. Every change listed below will be lost on the next recompile unless the compiler (spec, stub template, or extraction logic) is updated to produce it automatically.

This file tracks those changes so nothing is silently lost.

Already fixed in the compiler spec#

These items have corresponding rules or documentation. They will survive a recompile if the compiler implementer reads the spec.

  1. LaTeX math block preservation. The compiler was stripping \\ and & markers from .. math:: blocks, collapsing multi-line formulas into one overflowing line. Fixed by adding §9.3.1 to the skill spec (sisyf/ww/sisyf-skill.rst) and documented in AHA equations.rst.

    Action: None — already in spec. Implementer must follow §9.3.1.

Easy mechanical fixes#

These are straightforward template or extraction-logic changes. No design thinking required — just update the stub and the field-name mapping.

  1. Simplified field labels. The stub template uses verbose names like TechExplanationContext (tctx):. The hand-edited page uses short reader-facing labels. The mapping:

    Stub template name

    Hand-edited name

    ExplanationIntroOverview (intro):

    (dropped — unlabeled paragraph)

    FormalMathLatex (latex):

    Formal statement:

    TechExplanationContext (tctx):

    Context:

    TechExplanationContentAll (tcnt):

    Content:

    LogicsUsed (logic):

    Logic:

    TechReasoningAll (twhy):

    Reasoning:

    Limit (limit):

    Limit:

    NeedsFeed (needs):

    Depends on:

    FeedsNeed (feeds):

    Required by:

    ModelUsedIn (model):

    Model:

    VersionedVariantCurrent (vvnow):

    Version:

    KnownKiller (kk):

    Known objection:

    ConsRef (con):

    Critique:

    ProsRef (pro):

    Defense:

    DesignDoc (dd):

    Design:

    CollectedContent (cc):

    Prior art:

    WorkingWheel (ww):

    Cascade risk:

    SupportTorah (stor):

    Torah:

    SupportHebrewBible (sheb):

    Hebrew Bible:

    SupportGospels (sgos):

    Gospels:

    SupportApostolic (sapo):

    Apostolic:

    SupportQuran (squr):

    Quran:

    SupportSanskrit (ssan):

    Sanskrit:

    ViewSecular (vsec):

    Secular:

    Action: Add a display_name column to the extraction matrix or a label-mapping table in the spec. Update the stub template.

  2. Stub stripping. The hand-edited page omits every field whose content is [stub --- content pending]. The spec already has a --stubs option (drop, show, mark), but the stub template still emits all fields unconditionally.

    Action: Make --stubs drop the default for expert depth. The template should emit a field only if the PoR source has content for it.

  3. Lowercase heading prefixes. Headings use the lowercase id field (a1, a15), not uppercase ax1. Consistent with BEST Names grammar (always lowercase model-typeID).

    Action: Use id field for heading prefixes in the template.

  4. Identity block simplified. The stub template has a full “Identity” section with separate fields for id, title, name, sum. The hand-edited page replaces this with:

    • The heading itself carries id + title (a1 --- Containment)

    • A :ref: link back to the PoR source

    • An italic one-liner from the sum field

    • An unlabeled paragraph from the intro field

    Action: Collapse Identity fields into the heading + italic summary pattern. Drop the “Identity” section heading entirely.

  5. No .. contents:: directive. The stub template doesn’t include one either, but the first compile run added it. The hand-edited page removed it (the inline navigation bar at the top replaces it).

    Action: Ensure the compiler never emits .. contents::.

  6. Duplicate tinf field removed. The TechInformal field was appearing alongside intro, duplicating content. The hand-edited page keeps only the intro paragraph.

    Action: Drop tinf from expert depth extraction (it is a rewrite of intro for producer/easy audiences, not needed at expert depth).

Needs deeper thinking#

These changes involve structural decisions that go beyond template tweaks.

  1. Summary table at the top. The hand-edited page opens with a .. list-table:: showing all 25 axioms (id, title, one-line summary). This gives readers a map before diving into detail.

    Difficulty: The compiler must collect id, title, and sum from every element before emitting any element’s detail block. This requires a two-pass approach: first pass collects summary data, second pass emits the full page. The stub template (which is per-element) cannot express this.

    Action: Design a page-level preamble template separate from the per-element stub. The preamble template generates the table, nav bar, and intro paragraph. The per-element stub generates each axiom’s detail block.

  2. Inline navigation bar. The hand-edited page has a **Navigation:** line with a1 · a2 · ... · a25 anchor links. Like the summary table, this requires knowledge of all elements before emitting.

    Action: Same two-pass / page-preamble solution as item 8.

  3. Collapsible dropdowns for support and network sections. The hand-edited page uses .. dropdown:: (from sphinx-design) to collapse “Independent Support” and “Network & Dependencies” sections. This keeps the page scannable — readers see the formula and explanation without scrolling past seven tradition citations.

    Difficulty: The stub template uses plain headings. Switching to dropdowns requires (a) confirming sphinx-design is a permanent dependency, (b) updating the stub template to use .. dropdown:: syntax with :class-title: sd-font-weight-normal.

    Action: Decide whether sphinx-design is a permanent dependency (it is already in requirements.txt). If yes, update the stub. If no, use a <details> HTML fallback or plain headings.

10a. Expand all / Collapse all buttons. The hand-edited page adds

a #collapse-controls div that produces “Expand all” and “Collapse all” buttons. The collapse-sections.js was extended to toggle both custom collapsed sections and <details> elements (sphinx-design dropdowns). Documented in AHA/collapsible-details.md.

Status: JS extended (2026-03-25). The compiler must emit the controls div in the page preamble (same two-pass solution as items 8–9).

  1. Support fields as bullet list inside a single dropdown. The stub template lists each tradition as a separate labeled field (SupportTorah (stor):, SupportHebrewBible (sheb):, etc.). The hand-edited page merges them into a single bullet list under one “Independent Support” dropdown.

    Difficulty: Moderate. The compiler must iterate over all non-empty support fields and emit them as - **Label:** content items inside one dropdown, rather than as separate field blocks.

    Action: Add a “support group” rendering mode to the extraction logic. Similarly, network/structure fields are grouped into one “Network & Dependencies” dropdown with inline ·-separated model/version metadata.

  2. Group headings with contextual intros. The hand-edited page organizes axioms into groups (Group I --- Mereological Core, Group II --- Modal Framework, etc.) with a short paragraph explaining what the group covers. The PoR sources do not have explicit group metadata.

    Difficulty: Group membership and group descriptions are currently implicit (derived from axiom numbering ranges and human editorial judgment). The compiler has no structured data to generate them.

    Action: Either (a) add group metadata to the PoR sources (group: I, group_title: Mereological Core, group_intro: ...), or (b) hardcode group definitions in the compiler config, or (c) mark group headings as .. compiler:protected-section regions within the compiled page so they survive recompilation. Option (c) is quickest; option (a) is cleanest long-term.

  3. Labels must never start with a digit. HTML anchor IDs that begin with a number are silently truncated by Sphinx (e.g., 5d-link-naming-intro becomes d-link-naming-intro). This breaks cross-references and URLs. The issue affects any label, filename, or model name that starts with a digit (e.g., 4Be).

    Difficulty: Convention is easy; retrofitting existing names may require a naming policy for models whose natural identifier starts with a number (4Be → m4be? model-4be?).

    Action: (a) Add a rule to the 5D link naming doc: labels must start with a letter. (b) Design a prefix convention for model names that naturally start with a digit. (c) Audit all existing labels for violations.

Easy synthesis pages (pending SISYF runs)#

These pages are defined in the skill spec (§3.8) and documented in the synthesis how-to. Each should be created by following the AHA step by step — which also tests whether the instructions are complete.

  1. hebrew-bible (stor + sheb). Done (2026-03-26). File: axioms/easy/hebrew-bible.rst.

  2. gospels-apostles (sgos + sapo). Pending. File: axioms/easy/gospels-apostles.rst. Follow AHA: How to Create a Synthesis Page step by step.

  3. quran-based (squr + stor + sgos). Pending. File: axioms/easy/quran-based.rst. Quran as primary lens; Torah and Gospels as endorsed sources.

  4. secular (vsec). Pending. File: axioms/easy/secular.rst. Not a synthesis — 1:1 mapping from vsec field. Uses the same easy-page pattern (highlighted quote + expert link) but draws from a single source field.

Future: Social card comparison as compiler capability#

  1. Wide tables: LaTeX/PDF rendering. The Tier B standalone HTML tables (_static/socialcards/beginner-wide.html, producer-wide.html) are invisible to the LaTeX builder and will not appear in PDF output. The RST pages show only a 5-row preview. For PDF completeness, the script (scripts/gen_socialcard_tables.py) should also generate either:

    • A landscape-mode RST table (using .. raw:: latex environment wrappers) that the LaTeX builder can pick up, or

    • A Tier C (structured list) fallback that renders in both HTML and LaTeX but trades scanability for completeness.

    This applies to any future wide table, not just social cards. See AHA: Wide Table Formatting for Narrow RST Pages for the three-tier strategy.

    Action: When PDF output matters, extend the script to emit a LaTeX-compatible variant. Until then, the HTML-only wide tables are sufficient for the web deployment.

  2. Social card comparison tables. The script scripts/gen_socialcard_tables.py extracts SOCIAL-CARD-QUALITY-COMPARE blocks from all matheology RST files and generates five comparison/audit pages (beginner, producer, expert, flags, active). If future runs introduce additional quality levels (beyond OO and PP), or if the comparison needs to span sections outside matheology, this script may outgrow its current form. Efficient multi-level social card comparison — diffing metadata across quality tiers, flagging regressions, and regenerating audit tables on every compile — could deserve first-class compiler support rather than a standalone script.

    Action: Evaluate after a third quality tier is introduced. If the script needs significant changes at that point, promote the logic into the compiler’s post-processing pipeline.

How to use this list#

When implementing the compiler, work through this list top to bottom. After each item is incorporated into the spec/template/extraction logic, mark it done here with a date. When all items are done, the compiler can regenerate the expert page from scratch and produce output matching the hand-edited version — at which point this AA can be closed.