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.

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 <commit-hash>.

  • 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: <inferred> --- 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.

5. Risks and Mitigations#

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: LLog: Templates B (Study) and C (Raw) Refinement + Retro Transform Prompt (2026m04d20_11h39) (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).
Companion files
HELL: Historically Experienced Lessons Learned (there be dragons)

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.