Motivation

The problem

With LLMs generating both code and documentation from natural language prompts, there’s no authoritative representation of intent that persists across changes. Code and docs drift out of sync – and unlike the pre-LLM era where code was the single source of truth, now either artifact can be the one that’s “right.” This is the three-body problem: intent, code, and docs can all diverge.

The idea

Introduce a NotarAI spec – a structured YAML document governed by a JSON Schema – that captures user intent as the canonical source of truth. An LLM acts as the reconciliation engine, keeping code and documentation in sync with the spec (and vice versa).

Coverage model

Four tiers ensure every file in the repo is accounted for without over-specifying:

• Tier 1 (Full Spec): Business logic, APIs, user-facing features – full behaviors and constraints
• Tier 2 (Registered): Utility libs, sidecars, config – just intent + artifact mapping, no behaviors
• Tier 3 (Excluded): Generated code, vendor deps, editor configs – explicitly out of scope
• Tier 4 (Derived): Generated outputs tracked for staleness but not authored directly (build artifacts, compiled bundles)

Anything not covered by any tier is flagged as “unspecced” – a lint warning, not a blocker.

Bootstrap

For existing codebases: ingest code + docs + commit history, then the LLM interviews the developer about goals and undocumented rules, drafts a spec with required fields only, and the user reviews and enriches. The spec accrues precision over time.

Inspirations

See the Inspirations page.