Concepts overview

SpecLogician is built around a small set of composable building blocks.

Domain Model

A domain model can be arbitrarily complex. It typically contains:

• state/action structure
• predicates (state predicates, action predicates)
• transitions (functions that define behavior)
• domain-specific auxiliary logic

You can think of it as the “vocabulary” used to express scenarios and analyze artifacts.

Scenarios (given/when/then)

A scenario is a symbolic behavioral slice:

• given: constraints on state (what must be true before)
• when: constraints on action (what is attempted)
• then: transition(s) that should apply / be relevant

Scenarios are:

• local in scope
• declarative
• composable
• ideal for incremental changes produced by LLMs

Artifacts

Artifacts (tests, logs, docs, source references) provide evidence and grounding:

• test traces
• log traces
• docs / requirements
• source code references
• mappings between artifacts and formal components

State Instances and diffs

Every typed change produces a new StateInstance. SpecLogician computes:

• summary stats
• optional “heavy” presented objects (spec, artifacts)
• diffs between old/new states

This makes iteration safe and measurable: you always know what changed and whether it improved things.