format as constraint for documentation, modeling, problem-solving, and managing complexity.

ascii only
lowercase letters only
attempto controlled english
  no nested clauses; split into separate sentences
  only svo sentences: subject first, verb second, object last
one idea per sentence
prefer declaratives or process actives
  examples: "x stores y"; "the engine calls z"
canonical naming
  descriptive surface names
  one definition per idea; no synonyms or idioms
type-signature notation
  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 "}"
simplicity principles from ascii math
  totality: every function defined for all inputs, or returns explicit optional
  uniform syntax: same form for functions, arrays, sets
  full parenthesization: no operator precedence shortcuts
  desugaring discipline: all shorthand expands to core primitives
  explicit binding: quantifiers and indices bound visibly
  replace symbols with iteration: procedural clarity over glyph economy
  structural uniformity: functions, structs, traits share one definition style
  ban point-free style: all expressions named for clarity
  side conditions explicit: preconditions surfaced as optional types
  safe defaults: unsafe operations wrapped in checked versions
  transparency of proof: predicates and proofs written as explicit iteration
  notation expansion required: symbols must reduce to referential form
  shallow trait tagging: interfaces expressed as satisfied constraints
communication
  we shouldnt talk like we know everything

domain-specific specification sheet
  a compact field manual defining the essential dimensions, categories, and procedures
file: notes.it
  purpose
    capture exploratory, provisional material
    workspace for fragments that may become considerations.it or model.it entries
    hold volatile, incomplete, or speculative content
  contents
    free-form text, optionally indent-based trees
    tagged fragments for retrieval or grouping
    mixed prose, lists, sketches, pseudo-code permitted
  conventions
    indentation: 2 spaces for hierarchy when used
    tags: plain words or #tag inline
    no fixed ordering or section headers required
    entries may be partial, contradictory, or experimental
    preserve chronological flow; avoid post-facto restructuring except to annotate
  template
    ```
    {{topic or tag}}
      {{idea or fragment}}
        {{sub-detail}}
    {{another topic}}
      #tag
      {{note text}}
    ```
file: considerations.it
  purpose
    record design trajectory questions, decisions, rationale
    preserve historical trace of alternatives and chosen approach
    provide concise, context-rich reference for future maintenance
  structure
    sequential list of independent consideration entries
    each entry addresses a single design question
    implicit chronology by file ordering
  entry format
    ```
    {{question}}
      {{context and relevant facts for decision}}
      option - selected
        {{description, pros, cons}}
      option
        {{description, pros, cons}}
      option
        ...
    ```
  element definitions
    question: one-line interrogative defining the decision point
    context: minimal facts, constraints, or background directly relevant
    option - selected: adopted solution with brief justification and tradeoffs
    option: alternative not selected with disadvantages or reasons
file: general.it
  purpose
    minimal big picture specification
    stable, high-level conceptual description of a system or subsystem
    persistent orientation document
  meta-identity
    one or two sentences stating what the system is
    scope limits: explicitly note what it does not model
  global semantics
    evaluation model that applies everywhere
    cross-cutting properties (deterministic, cycle-free, block-wise, immutable, etc.)
  global carriers
    major structures that span the whole system
    described as abstract containers, not implementation
  general rules
    invariant conventions that always hold
    examples: interval half-openness, immutability, duration rules, structural analogies across layers
file: model.it
  purpose
    define procedures, functions, and data structures
    keep linear, sparse, parseable
  contents
    name: single-line identifier and description
    procedures: specifies ordered operational steps; defines how the construct transforms inputs into outputs
    functions: lists callable interfaces by signature; defines how the construct composes with other constructs
    structures: specifies the internal organization of fields and types bound to a single identifier
  conventions
    indentation: 2 spaces
    naming: lowercase_with_underscores
    fields are positional - one per line
    no prose outside description or designated sections
    multiple files allowed; one model per file
  template
    # {{model name}}
    concise role: one-line purpose
    distinctive principle: what separates this construct from others
    ## procedures
    ordered specification of behavior
      base case(s): condition -> result
      recursive/iterative case(s): condition -> progression
      invariants: local properties preserved
      description must be language-independent
    ## functions
    callable interfaces
    signatures written in the defined syntax:
      signature ::= input "->" output
      multiple   ::= element element ...
      alternates ::= element "/" element ...
      names      ::= type ":" alias ...
      optional   ::= "[" element ... "]"
      repetition ::= element "..."
      naming     ::= name "::" arguments "->" result
      list       ::= "(" element ... ")"
      map_or_fn  ::= "{" key_or_input "->" value_or_output "}"
    ## structures
    abstract domains manipulated by this construct
    entity format:
      name
        field
        field/type
        ...
field manual meta
  not a tutorial, not a style guide, not a reference manual
  practical operational handbook: concise, procedural, technology-agnostic
  designed for rapid onboarding into unfamiliar codebases
  essentials-first: core questions (20q kernel) provide minimum initialization bandwidth
  layered: sections start with high-leverage questions, then expand to structured fact categories, methods, outputs
  taxonomy plus protocol: classification of knowledge with action protocols
  neutral and systematic: avoids frameworks or tools, favors orthogonal abstractions
  goals
    make an experienced developer productive quickly in maintenance tasks
    give a chatbot or human a prioritized probe set to acquire system understanding
    enforce reproducibility, minimize error, converge efficiently on solutions
documentation systems
  versioned rendered readme hierarchy (gitlab)
  pdf
  not suitable: nextcloud
    cant do internal links of any kind
    no image rendering
definition formats
  templated; like scheme macro syntax
  ebnf

referential transparency
  output depends only on input
  expressions replaceable by their values
idempotency
  if suitable, operations yield same result on repetition
falsifiability
  claims must be testable or refutable
strict call by contract
  no asserts and defensive checks outside the contract
a bug that results from proper usage
  example framing: adhering exactly to the contract still fails; classify as specification bug
software development is managing complexity

orthogonal primitives
  new constructs must justify themselves as orthogonal
  larger systems form by composition of minimal parts
software described on three axes: procedures, functions, structures
minimize coupling
discipline
  even if it is not perfect, prepare it to become so
economy
  do one thing well
  remove nonessential parts
  avoid redundancy, excess abstraction, or special cases
proportionality
  solution matches scale of problem
  progressive disclosure: expose complexity only when needed
  principle of least surprise: behavior matches expectation
convention over configuration
  avoid speculative future needs
no hidden registries or autowiring

what it means to encode identity
  language-independent description of the method; enough to distinguish families (e.g., quicksort vs mergesort)
  choose abstraction level: ignore machine details, retain defining recurrence/partitioning
  respect church-turing boundary: reducible to effective procedure
  judged by clarity of essential steps, elided implementation detail, support for reasoning (correctness, termination, invariants)
variable elements and abstraction
  treat domains abstractly when only properties matter
  concrete representation unnecessary unless algorithm depends on specifics
  example: quicksort needs total order; carrier width irrelevant if "<" consistent
  if overflow or rounding matters, drop abstraction to concrete representation
  principle: keep abstraction at level of properties essential to identity; refine when representation affects correctness
semantic styles
  operational semantics: state transitions, imperative pseudocode, asms
  denotational semantics: input-output mappings, recurrences, set-theoretic relations
  algebraic semantics: equations and laws, algebraic specification, horn clauses
refinement principle
  start with high-level specification (identity: permutation + sortedness)
  refine stepwise to partition-based recurrence, then pseudocode, then machine code
  preserve correctness; refined implies original
encodings of identity
  natural language description
  imperative pseudocode
  horn clauses / logic programming
  mathematical recurrence equations
  algebraic specifications (equational logic)
  set-theoretic relations (input/output + invariants)
  category-theoretic combinators (folds, catamorphisms)
  abstract state machines
  type-theoretic/refinement type specs
  flowcharts or control-flow graphs
  mealy machine morphisms (state-based transducers)
functional programming as substrate
  treat functional paradigm as canonical encoding
  any algorithm expressed in a purely functional form can be projected into imperative, object-oriented, or state-based implementations.
    the converse does not hold: implementations originating in other paradigms may rely on side effects, hidden state,
      or control flow constructs that cannot be mapped back into a functional core without loss or redefinition.
  reasons
    emphasizes referential transparency, totality, explicit data flow
    aligns with algebraic, denotational, and type-theoretic semantics
    offers a minimal substrate for defining algorithmic identity
  role
    serve as common representation from which imperative, object-oriented, or state-based styles can be derived
    encoding in functional core ensures clarity, then project into other paradigms for implementation
  consequence
    identity expressed once; implementations vary by projection
    reduces ambiguity, enforces orthogonality across styles

primary vectorization
  identify orthogonal primary variables {v1, ... , vn} spanning the space
recursive orthogonalization
  for each vi, define orthogonal subvariables to refine coverage
minimum-questions protocol for low-bandwidth priming
  20 questions framing: each question carves search space, reduces ambiguity, connects categories
  prioritized subset: smallest high-leverage fact set that unlocks broad understanding
rule: any two variables define the third
  guarantees completeness: specifying any two components yields a unique third
  enables inversion-based techniques: reverse execution, program synthesis, input recovery
  allows bidirectional reasoning: flip knowns/unknowns without changing model
  detects underdetermination early: single known implies multiple completions
  supports automated tooling: one core serves three tasks by permuting roles
  examples
    database: (query, dataset) -> result
    simulation: (initial, rules) -> final
    testing: (program, input) -> output
certainty thresholding
  assign certainty c in [0, 1] to each vector element
  if c < tau, stop deterministic enumeration
exploratory optioning
  for incomplete vectors, pose questions defining unknown dimensions
  enumerate plausible options {o1, o2, ...} with constraints and implications
rationale optimization
  evaluate options against objectives, constraints, tradeoffs
  select optimal or provisional; mark unresolved for iteration
economic data interpretation
  do not waste dimensions
high and low probability assignments
  maintain explicit priors and thresholds

general
  si or planck units only
  specifications are treated as falsifiable hypotheses, abstractions are defined by explicit operations, refinements proceed stepwise while preserving correctness,
    anomalies are surfaced through orthogonality checks and minimal-question protocols, probability assignments update with evidence, and all outputs must be reproducible and verifiable.
languages
  no hidden control flow
  predictable cost model
  no operator overloading
  inline when small and less than three usages
  outline when large or more than two usages
software
  no error handling
  strict call by contract
  no asserts and defensive checks outside the contract
  not following conventions; if not part of the syntax it is usually not worth following
  artifacts
    language-independent description of the method
    function signatures
    explanation simplified enough to distinguish it from x
    encoding algorithmic identity
    how one developer explains it to another in a short time span
    reduces the codebase to orthogonal fact categories learnable incrementally

dont abstract what is not used or not complex
think of the call hierarchy and keep it tidy
pitfall prompt
  if one piece of code tries to do multiple things at once, or multiple parts do something that should be centralized in one part

intermediate formats; define mappings
word clusters, idea lists, vocabulary building, keyword sets, demarcation keywords, group headings
list open issues
create tuples of variables as set elements; map the space with variable tuples
define interface layers
it doesnt need to be perfect, but prepare it to become so
  design for clarity and extendability, not premature completeness

are there shared fundamentals between these two families that could improve either
does this application or usage expose flaws in the generality or orthogonality of availability
  "this use case reveals a few pressure points where availability isn’t fully general or perfectly orthogonal yet. below are the frictions and tight, actionable fixes".