:orphan: .. include:: /_templates/include-file/page-prefix.rst **************************************************************************************************** Prompt: Retroactive Site-Wide Template Transform (2026m04d20_11h39) **************************************************************************************************** Draft prompt for transforming all existing balospe.com documents to conform to the three-template system defined in ``AHA/document-beginnings.md``. This is a high-blast-radius operation. Do NOT execute without LLoL's explicit approval of the full plan below. .. contents:: Contents :depth: 2 :local: ---- 1. Scope =========== The current balospe.com repo contains approximately [to be counted] RST and MD files across ``source/`` and ``AHA/``. Each must be classified into one of three templates and brought into conformance. **Three-template targets:** - **Template A (Front pages):** [`AHA/page-template.md`] + [`page-template-to-instantiate-copy.rst`] - **Template B (Study pages):** [`AHA/page-template_b_study-pages.md`] — arxiv-ready. - **Template C (Raw pages):** [`AHA/page-template_c_raw-pages.md`] — internal production files. **Not in scope:** Files in ``build/`` (generated), ``locale/`` (translation ``.po``), ``.claude/`` (Claude settings), ``node_modules/`` (if any), ``.git/``, archived / obsolete content. ---- 2. Safety and Datageddon Avoidance ======================================= 2.1 Work in a branch ----------------------- All work on a dedicated branch (suggested: ``retro-template-transform``). Main branch stays clean. No pushes to main until LLoL approves the branch. 2.2 Pilot before batch -------------------------- Before any batch execution: 1. Pick 2 files --- one Study-page candidate (e.g., b11 paper), one Raw-page candidate (e.g., one 2026m04d07 llog). 2. Apply the transform to those two files only. 3. LLoL reviews the result. 4. If LLoL approves, proceed to batch. If not, adjust the spec or the transform script, re-pilot. 2.3 Batch by type, not alphabetically ---------------------------------------- Do NOT transform "all files in ``source/``" as one atomic operation. Batch by type: 1. **Matheo papers** (b11--b18 main papers) → Template B. (~10--15 files.) 2. **LLogs** (``hell/ll/**/*llog*.rst``) → Template C. (~50--100 files.) 3. **Prompt files** (``hell/ll/**/*prompt*.rst``) → Template C. (~20--30 files.) 4. **Growth Garden / Design Doc / KB / review files** → Template C. (~10--30 files.) 5. **Indexes** (``aaa.rst``, ``b18-overview.rst``, etc.) → Template C. 6. **Matheo sub-papers** (intro, theophil, socpsy, etc.) → Template B. 7. **Front-facing content pages** (index, intro, faq, action) → Template A. (These already use ``AHA/page-template.md``; verify conformance rather than transform.) Each batch is a separate commit on the branch. Rollback granularity = one batch. 2.4 Checkpoint after each batch ----------------------------------- After each batch: - Run ``make clean && make dev``. Verify zero NEW Sphinx warnings. (Existing warnings are OK; new warnings introduced by the transform must be fixed before proceeding.) - Verify cross-references still resolve (``sphinx-build -b linkcheck`` if feasible; or grep for broken ``:doc:`` references). - LLoL reviews a sample of transformed files. - Commit the batch with a descriptive message. Tag the commit for easy rollback. 2.5 Rollback plan -------------------- - Any single batch can be reverted via ``git revert ``. - If the whole transform needs to be abandoned, the branch can be deleted without affecting main. - Keep tags at the start of each batch for checkpoint-level rollback. ---- 3. Per-File Transform (What Changes) ========================================= 3.1 Template A (Front pages) --- verify-only transform --------------------------------------------------------- For files already using ``AHA/page-template.md``: 1. Verify ``.. meta::`` block is present with ``:description:``, ``:keywords:``, ``:author:``. 2. Verify first paragraph is SEO-usable. 3. Verify footer form (open-std or shut-std) is present and uses current ``MailForm=OOv2r0p0`` syntax. 4. VVN: if present in page-status annotation, update to the current format. If absent, leave absent (Front pages don't require a prominent VVN; the page-status annotation is enough). 5. Do NOT restructure. Do NOT move metadata to end (this is what makes A different from B and C). 3.2 Template B (Study pages) --- restructure ----------------------------------------------- For Matheo series papers and academic sub-papers: 1. **Title:** Remove any timestamp from the title string. Keep the filename's timestamp. 2. **Top metadata block:** - If the current file has a large ``.. note::`` block with draft status, VVN, etc., REPLACE with a small **Supplementary (brief)** ``.. note::`` block containing only: ``VVN (Hu):`` (blank if not assigned), ``VVN (Ma):`` (corrected format), ``Draft:`` date, and any short details LLoL had on the original. 3. **Abstract / Broader Significance:** - If these sections exist as RST headings, convert them to ``**Abstract**`` / ``**Broader Significance**`` bold text (NOT headings). - If Broader Significance does not yet exist, add a ``[TODO: write Broader Significance]`` marker for LLoL to fill in later. 4. **Local TOC:** - Insert ``.. contents:: Contents`` with ``:depth: 2`` and ``:local:`` directly AFTER Broader Significance and BEFORE the first numbered section. 5. **Body:** Leave numbered sections (1. Introduction, 2. ...) as-is. 6. **Acknowledgements:** Leave as RST heading where it exists. If absent, add a ``[TODO: write Acknowledgements]`` marker. 7. **Supplementary (long):** - Add a new ``Supplementary`` RST heading after Acknowledgements and before References. - Populate with the 7 sub-items (S.1 Code/Data, S.2 Prompts, S.3 LLogs, S.4 Reviews, S.5 AI Model Disclosure, S.6 Correction Log, S.7 License). - Fill in what can be inferred from existing material; mark rest as ``[TODO: LLoL to fill]``. 8. **References:** Leave as-is. 9. **End dropdowns:** - Add Companion papers dropdown (``:open:``) listing cross-references to sibling Matheo papers (extracted from existing ``:doc:`` references in the paper). - Add HELL dropdown (``:closed:``) with the standard warning text, listing links to the paper's llogs, prompts, and reviews. 10. **VVN format:** Update any inline VVN strings to ``[content-prefix]-[dv/iv]_[Assessor]_[StabilityCodeVRP]_[timestamp]`` per ``AHA/vvn-composition.md``. Bump ``p`` counter to mark the retro-transform patch. 3.3 Template C (Raw pages) --- restructure ---------------------------------------------- For llogs, prompts, GG, DD, reviews, KBs, indexes: 1. **Title:** Remove any timestamp from the title string. Keep filename as-is. 2. **Context paragraph:** If the file has a large ``.. note::`` block at the top, replace with a 1--2 line context paragraph (extracted or written) under the title. 3. **Local TOC:** Insert ``.. contents::`` directly after the context paragraph. 4. **Body:** Leave numbered sections / verbatim prompts as-is. 5. **End Notes block:** - Add ``Notes`` RST heading at the end. - Populate with ``VVN (Hu):``, ``VVN (Ma):``, ``POST code:``, ``Mode:``, ``Effort:``, ``Trigger prompt:``, ``Companion documents:``, ``Output files:``. - Extract values from existing header block. 6. **End dropdowns:** - Companion papers/llogs dropdown (``:open:``). - HELL dropdown (``:closed:``) with standard warning. 7. **POST code:** - For files currently in the POST system (AA, AAA, etc.), preserve their classification. - For files without an explicit POST code, infer from filename / directory and add as ``[POST code: --- LLoL to confirm]``. 8. **VVN format:** Same as Template B rules. 3.4 LLogs specifically --- append, don't edit ------------------------------------------------- LLogs are append-only audit trails. For existing llogs: - The transform MAY update structural elements (title, TOC, end Notes block) because these are metadata, not content. - The transform MUST NOT edit the historical content --- verbatim prompts, responses, analyses stay as written. - The historical VVN at the top of each llog (even if malformed by the current convention) STAYS. Add a NEW correction note at the end of the Notes block: "Original VVN: [old string]. Corrected per ``AHA/vvn-composition.md``: [new string]." This preserves the audit trail while updating the display format. ---- 4. Execution Order (Recommended) ==================================== Session 1 (pilot): - Create branch. - Transform 2 files (1 Study pilot, 1 Raw pilot). - LLoL reviews. - Adjust transform rules if needed. Session 2 (llogs batch): - Transform all llogs (~50--100 files). - Run ``make dev``. Verify zero new warnings. - LLoL reviews sample. - Commit. Session 3 (prompts batch): - Same pattern for prompt files. Session 4 (GG/DD/KB/review batch): - Same. Session 5 (indexes batch): - ``aaa.rst``, ``b18-overview.rst``, and similar. Session 6 (Matheo papers batch): - b11 through b18 papers and academic sub-papers. Session 7 (Front-pages verify-only): - Spot check. Front pages should already conform. Session 8 (merge): - LLoL reviews full branch diff. - Merge to main. - Deploy. Estimated total: 7--10 working sessions. Adjust based on pilot findings. ---- 5. Risks and Mitigations ============================= .. list-table:: :header-rows: 1 :widths: 30 40 30 * - Risk - Likelihood - Mitigation * - Broken cross-references (``:doc:`` / ``:ref:``) - High (any restructure risks this) - Run ``sphinx-build`` after each batch; fix warnings before commit. * - Lost historical VVN strings in llogs - Medium (transform could overwrite) - §3.4: append correction note, preserve historical string. * - Transform applied to wrong template class - Medium (classification errors) - Pilot first; batch by file-type pattern; LLoL reviews. * - Build breakage (Sphinx errors) - Low-medium - ``make dev`` after each batch; rollback one batch if needed. * - Site rendering looks worse after transform - Low - Pilot review catches this; adjust spec. * - LLoL preferences evolve mid-transform - High (this is a long project) - Each session commits; changes apply to subsequent files only. * - Lost rejected-draft variants in ``ach/`` folders - Low (those are already archived) - Explicit rule: do not touch ``ach/`` folders. ---- 6. Open Questions (Before Execution) ========================================== - **POST code registry:** Template C's POST field needs the authoritative list from LLoL. Partial list in ``AHA/POST.md``; full list in LLoL's head. - **Which files get ``VVN (Hu)`` during the transform vs. left blank for later?** Blanket rule: leave ``VVN (Hu):`` blank during the transform. LLoL assigns it when reviewing. - **Figures twice retroactive:** For existing Matheo papers with inline figures, do we add the Figures-at-Full-Size appendix retroactively, or only for new papers? - **SGIR paper specifically:** Already very close to Template B. Does it serve as the "pilot" for Session 1, or is a smaller / simpler paper preferred for the pilot? - **Hardcoded VVN references in other files** (e.g., aaa.rst): if a VVN is cited in aaa.rst and the source file's VVN updates, do we update the citation too? (Yes, recommend; but this doubles the transform scope.) ---- 7. What the Transform Produces (Success Criteria) ======================================================= After transform complete: 1. Every file in ``source/`` and ``AHA/`` classified as A, B, or C. 2. Every Study-page file conforms to [`AHA/page-template_b_study-pages.md`]. 3. Every Raw-page file conforms to [`AHA/page-template_c_raw-pages.md`]. 4. Every Front-page file conforms to [`AHA/page-template.md`] (verified). 5. Every file has a correctly-formatted VVN (Ma) per [`AHA/vvn-composition.md`]. 6. Every llog has preserved its historical VVN alongside the corrected one. 7. ``make clean && make dev`` produces zero new Sphinx warnings. 8. All ``:doc:`` and ``:ref:`` cross-references resolve. 9. LLoL can find the same content in its new location / structure. 10. Audit trail is intact (git log of each batch is legible). ---- Notes ======= | **VVN (Hu):** (not yet assigned) | **VVN (Ma):** ``retro-template-transform-dv_ClaOp47Max_MMv1r0p0_2026m04d20_11h39`` | **POST code:** (prompt --- suggest PP for PathProbing or specific prompt code; ASK LLoL) | **Mode:** EDEN | **Effort:** Max | **Status:** DRAFT --- awaits LLoL review before execution. | **Companion documents:** :doc:`/matheology/hell/ll/infra/b/11/study_ll_2026m04d20_11h39_templates-b-c-refinement-llog` (the session that produced this prompt); ``AHA/document-beginnings.md``; ``AHA/page-template_b_study-pages.md``; ``AHA/page-template_c_raw-pages.md``; ``AHA/vvn-composition.md``. | **Output files (when executed):** All files in ``source/`` and ``AHA/`` will be touched (read and possibly modified). ---- .. dropdown:: Companion files :open: - :doc:`/matheology/hell/ll/infra/b/11/study_ll_2026m04d20_11h39_templates-b-c-refinement-llog` --- session that produced this prompt - ``AHA/document-beginnings.md`` --- three-template overview - ``AHA/page-template_b_study-pages.md`` --- Template B full spec - ``AHA/page-template_c_raw-pages.md`` --- Template C full spec - ``AHA/vvn-composition.md`` --- VVN format - ``AHA/page-template.md`` --- Template A spec (preserved for Front pages) .. dropdown:: HELL: Historically Experienced Lessons Learned (there be dragons) :class-container: page-footer-hell-warning **Beware.** This prompt was drafted without LLoL's review of the underlying template specs. Execution details may need adjustment based on pilot findings. Content may be rough, draft-quality, or outdated. There be dragons. End of prompt.