# implementation

all these files can be split into multiple files depending on content size.

## goals
* a domain-specific specification sheet
* a compact field manual defining essential dimensions, categories, and procedures.
* build a probe set for humans or chatbots to acquire system understanding

## file: `notes.it`
### purpose
* capture exploratory or provisional material
* workspace for fragments that may later become `considerations.it` or `model.it` entries
* hold volatile, incomplete, or speculative content

### contents
* free-form text; optionally indent-based trees
* may include prose, lists, sketches, or pseudo-code
* entries may be partial, contradictory, or experimental

### template
```
{{topic}}
  {{idea or fragment}}
    {{sub-detail}}
{{another topic}}
  {{note text}}
```

## file: `considerations.it`
### purpose
* record design trajectory, questions, decisions, and rationale
* preserve a historical trace of alternatives and chosen approaches
* provide concise, context-rich reference for future maintenance

### structure
* sequential list of independent consideration entries
* each entry addresses a single design question
* chronological order implied by file sequence

### 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, without question mark, defining the decision point
* context - minimal facts, constraints, or relevant background
* option - selected - adopted solution
* option - alternative not selected

## file: `general.it`
### purpose
* provides the minimal big-picture specification
* stable, high-level conceptual description of the whole system
* global semantics
* cross-cutting properties
* invariant conventions that always hold

## file: model.it
### purpose
software described on three axes: procedures, functions, structures:
* the first describes alghorithms and evaluation
* the second describes the api in function signatures
* the third describes the carrier entities with fields

### template
```
# {{model name}}
concise role: one-line purpose
distinctive principle: what separates his construct from others

## procedures
ordered specification of behavior.
a language-independent encoding of algorithmic identity.

## functions
callable interfaces
signatures written in the 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
entity format:
  name
    field
    field: type
    ...
```