name: theorist-mode description: | Activate theoretical foundations context for discussions about Grafema's formal underpinnings, multi-language strategy, cognitive science, and abstract architecture. Use when: (1) discussing formal languages, type theory, abstract interpretation, (2) planning multi-language support, (3) designing metrics or benchmarks, (4) reasoning about completeness and soundness of analysis, (5) positioning Grafema academically. author: Vadim Reshetnikov + Claude Code version: 1.0.0 date: 2026-03-03 tags: [research, theory, architecture, cognitive-science]
Theorist Mode
Activation
Load full theoretical context before discussing abstract/formal topics.
Required Context — Read These Files First
_ai/research/theoretical-foundations.md— 5 abstraction levels, all theories, Cognitive Dimensions, evidence base, LLM benchmark design, academic partnership strategy_ai/research/declarative-semantic-rules.md— semantic rules matrix, flow rules, completeness guarantees, prior art (Spoofax, CodeQL, Joern)
Key Concepts Quick Reference
The Five Levels
L5: Cognitive Model → Cognitive Dimensions of Notations (Green & Petre)
L4: Paradigm → Denotational Semantics
L3: Semantic Projections → Abstract Interpretation (Cousot & Cousot)
L2: Semantic Roles → Operational Semantics
L1: AST Node Types → Formal Grammars (Chomsky)
L0: Source Code
Core Vocabulary
- Semantic projection — DFG, CFG, Scope etc. Each is an abstract interpretation of full program semantics
- Semantic role — cross-language operation class: Callable, Invocation, Declaration, Import, Assignment, Access, Control
- Flow rule — operational semantics for one AST node type in one projection:
ConditionalExpression.DFG → consequent|alternate flows to parent - Soundness — no false negatives. If there's a real dependency, the graph shows it
- Completeness — every relevant AST node type has a rule for every applicable projection
- Functor — mapping between abstraction levels (AST→Graph, Graph→DFG, Graph→Haskell types)
- Cognitive load — intrinsic (task complexity) + extraneous (tool friction) + germane (building mental model). Grafema reduces extraneous and pre-builds germane.
Grafema's Theoretical Identity
"Haskell for untyped code" — Grafema builds what Haskell's type system provides natively, but for languages where types don't exist.
| Haskell | Grafema |
|---|---|
| Type signatures | Graph edges (RETURNS, THROWS, TRANSFORMS) |
| Exhaustiveness checking | Semantic rules matrix |
| Type class laws | Guarantees (grafema check) |
| Hoogle (search by type) | find_nodes (search by graph) |
| Compiler rejects inconsistencies | grafema check rejects broken guarantees |
The Key Number
Developers spend 58% of time on code comprehension. A tool that speeds this up by 30% saves 17% of total developer time. For 50 developers = 8.5 FTE.
Multi-Language Strategy
Best-in-class parser per language (NOT tree-sitter). AST = human understanding, CST = "code of code".
| Language | Parser | Complexity | MVP weeks |
|---|---|---|---|
| JS/TS | Babel | Baseline | Done |
| Java | JavaParser | Low | 2-3 |
| Kotlin | kotlin-compiler (PSI) | Medium-Low | 3-4 |
| Swift | SwiftSyntax | Medium | 4-5 |
| Obj-C | libclang | High | 6-8 |
Order: Java first (simplest, reveals JS-coupling), then Kotlin → Swift → Obj-C.
Completeness Chain
@babel/types spec
→ generate semantic rules matrix (180 nodes × 7 projections)
→ generate visitors/edges from rules
→ graph is provably complete
→ LLM benchmark shows improvement
→ human study at ICPC/PPIG confirms
Discussion Guidelines
When in theorist mode:
- Use formal vocabulary — "semantic projection" not "analysis type", "soundness" not "completeness-ish"
- Reference the levels — "this is an L3 concern (projection design)" or "this is L5 (cognitive impact)"
- Connect to evidence — cite the 58% comprehension number, NASA-TLX, Cousot & Cousot
- Think in functors — "this transformation preserves/loses what properties?"
- Check prior art — before proposing, check if Spoofax/CodeQL/Joern already solved it
- Measure — every claim should have a measurable metric attached