named data carriers with fields; each field may state a type after a colon or a topology in round brackets structures with less than three fields should be avoided. collections can be designated by using the english plural on a type, by using an ellipsis, or round brackets for nested collections.

avoid confusing value identifiers (always means the exact same thing) with type identifiers (only means the same type or structure), as well as confusing descriptions with identifiers (which leads to a proliferation of identifiers when they contain descriptive phrasing).

function signatures that describe callable units, and associated input and output types with the following syntax:

signature: input " -> " output
multiple: element (" " element) ...
alternatives: element ("/" element) ...
names: type ":" alias ...
optional: "[" element ... "]"
repetition: element " " "..."
naming: name " :: " arguments "->" result
list: "(" element ... ")"
map_or_function: "{" key_or_input " -> " value_or_output "}"

descriptions of function bodies by encoding the algorithmic identity just as far as is necessary to serve the overall system. the goal is to enable construction of suitable implementations.

• capture why each design decision exists
• record how the decision space evolved
• enable future readers to reconstruct context without redoing the analysis

• represent each consideration as a 3 item structure: question, options, selection.
• an option is any candidate answer paired with its attributes such as pros and cons.
• in cases where there is only one plausible answer, record a single option whose attributes state the reasoning; the selection is that option. this encodes (question, reason, answer).
• in cases with multiple candidates, list all options with their attributes and mark the chosen one as the selection.
• the short form is therefore a single option instance; the long form is multiple option instances.

{{question}}
  {{context}}
  option - selected
    {{attributes}}
  option
    {{attributes}}
  option
    ...

• question: single-line interrogative phrase defining the decision point, written without a trailing question mark
• context: minimal constraints, facts, or background needed to interpret the options
• option - selected: the adopted solution
• option: a considered but unselected alternative
• attributes: any combination of description, evaluation criteria, advantages, disadvantages, constraints, or other facts relevant to comparing this option
• if an option introduces substantial branching, create a separate entry for that branch

• record exploratory, provisional, or uncertain material
• serve as a staging area for content that may later migrate into structured files
• hold volatile or speculative reasoning without committing to final form

• unconstrained free-form text
• any mixture of prose, lists, sketches, or pseudo-code
• material may be incomplete, conflicting, or intentionally experimental

{{topic}}
  {{idea or fragment}}
    {{sub-detail}}
{{topic}}
  {{note text}}

• state the minimal high-level specification of the system
• define stable conceptual foundations and system-wide intent
• record global semantics and cross-cutting properties that anchor all other files

• concise overarching principles and invariant domain concepts
• system-wide assumptions and semantics
• definitions required for consistent interpretation of all subordinate documents
• algorithmic hierarchy: high-level list of algorithms and how they compose the feature