.. meta::
   :description: Design document defining HELL's lettered-numbering system for stable, extensible, humane long-term referencing.
   :keywords: lettered numbering, HELL, design document, a1-a9, b10-b99, c100-c999, OLT, stable referencing, FLAMES
   :author: Yah, Yas, everyone, LLoL as Laurence Loewe of Laodicea, ClaudeOp46Max, Anthropic, and The Spirit of Boolean Truth

.. _hell-dd-b11-lettered-numbering:


***********************************************************************
DD b11 --- Lettered-Numbering System for HELL References
***********************************************************************

This design document defines the **lettered-numbering system** used throughout
HELL for stable, extensible, humane (OLT) referencing of all items --- salt
crystals, session logs, mockup models, design documents, aims, and more.

The system assigns every item a short, memorable, permanent identifier that
encodes its order of magnitude. It is designed so that:

- **Stable**: numbers never change once assigned; links survive indefinitely.
- **Extensible**: new magnitude bands open automatically as items grow.
- **Humane**: short identifiers (``b11``, ``c102``) are easy to speak, type,
  and remember.

.. contents:: On this page
   :depth: 2
   :local:


----


The System
===========

Bands and Ranges
------------------

Each band is a single lowercase letter followed by a fixed number of digits.
The letter encodes the order of magnitude:

.. list-table::
   :header-rows: 1
   :widths: 10 20 15 15 40

   * - Band
     - Range
     - Capacity
     - Digits
     - Purpose
   * - **a**
     - a1 -- a9
     - 9
     - 1
     - Reserved for greatest hits, hall-of-fame entries, and foundational items.
   * - **b**
     - b10 -- b99
     - 90
     - 2
     - Standard operating range. b10 is reserved for the format template of
       its parent sequence. First usable entry is **b11**.
   * - **c**
     - c100 -- c999
     - 900
     - 3
     - Extended range, opens when b-band fills up (or when the item
       naturally belongs to a higher-magnitude collection, e.g., bug reports).
   * - **d**
     - d1000 -- d9999
     - 9000
     - 4
     - Large-scale range. Unlikely to be needed soon.
   * - **e** ...
     - e10000 -- ...
     - 90000 ...
     - 5+
     - The pattern continues indefinitely. Each new letter adds one digit.

.. note::

   The system is isomorphic to base-10 counting with a letter prefix marking
   the number of digits. It never runs out of bands.


Reserved Slots
----------------

In every numbered sequence:

- **a1 -- a9**: Reserved for the most important or foundational entries.
  These slots are assigned *retroactively* once it is clear which entries
  deserve them. They are NOT assigned during normal sequential numbering.
- **b10**: Reserved for the **format template** of the sequence. It defines
  the canonical structure for all entries in that sequence and documents how
  and when to update entries in older formats. It also records the **next
  free number** for the sequence.

The first entry created in normal workflow is always **b11**.


Assignment Rules
------------------

1. **Sequential**: new entries receive the next available number in the
   b-band (b11, b12, b13, ...). Never skip numbers.
2. **Permanent**: once a number is assigned, it is never reassigned, even
   if the entry is deprecated or moved to HH (HistoryHeap).
3. **Cross-band references**: an entry at ``b17`` can reference entries in
   any band (``a3``, ``c102``, etc.). The band letter is part of the
   identifier and must always be included.
4. **Promotion to a-band**: when a b-band entry proves to be foundational,
   it *may* be promoted to an a-band slot. The b-band entry then becomes a
   forwarding pointer (not deleted). Promotion requires explicit human
   approval.
5. **Next free number**: every ``index.rst`` of a numbered sequence MUST
   state the next free number as a comment or visible note. This prevents
   collisions and removes guesswork.


Directory Convention
----------------------

Each numbered entry gets its own directory:

.. code-block:: text

   hell/<section>/b/11/index.rst
   hell/<section>/b/11/<additional-files>
   hell/<section>/b/12/index.rst
   ...

For session logs, the directory also contains the long descriptive filename:

.. code-block:: text

   hell/ll/promy/b/11/promy_ll_2026m03d29_pipeline-test.rst
   hell/ll/other/b/11/other_ll_2026m04d03_prompt-hell-restructuring.rst

The numbered directory (``b/11/``) is the stable reference. The long filename
inside it is the human-readable description. Both survive indefinitely.


Scope of Application
-----------------------

This lettered-numbering system applies to ALL numbered sequences in HELL:

- ``hell/salt/b/11/`` --- salt crystals (adversarial review summaries)
- ``hell/ll/<tool>/b/11/`` --- session logs by tool type
- ``hell/mm/b/11/`` --- mockup models (drafts)
- ``hell/system/dd/b/11/`` --- design documents (this document)
- ``hell/aa/b/11/`` --- aims and tasks
- ``hell/ff/b/11/`` --- feedback entries
- ``hell/ee/b/11/`` --- enclosed evidence
- ``hell/bug/c/101/`` --- bug reports (already using c-band)
- ``hell/con/b/11/`` --- adversarial objections (existing, stable)
- ``hell/pro/b/11/`` --- adversarial responses (existing, stable)


EDEN Classification
---------------------

I found this **Green Meadow #1** in EDEN: the lettered-numbering system is
stable OLT because it is isomorphic to the natural numbers with a
magnitude-prefix. It cannot run out of bands. The reserved a-band and b10
template slot prevent premature assignment of prestigious slots while ensuring
every sequence is self-documenting. count = Inf (infinite valid numbering
choices; this particular scheme is the simplest that satisfies all three OLT
criteria: stable, extensible, humane).


----


*This design document was created on 2026m04d03 during the HELL Stability
Review and FLAMES Restructuring session.*