1 / 12

AI manages your infra...
Do you know what's happening?

Ontology and Reflection as the ground of a project that understands itself.

The problem is not the tool

What AI does well

✓

Generates syntactically correct YAML

✓

Completes Terraform that never breaks the plan

✓

Fills configuration gaps with reasonable defaults

✓

Translates intent into declarative form

What AI cannot do

✗

Know why that service cannot scale to N replicas

✗

Know the tension between latency and consistency in your system

✗

Remember the decision you made in December and why you rejected the alternative

✗

Understand what cannot break without cross-team coordination

Declarative ≠ understanding.
You describe the desired state, not the why.

2am — when Terraform won’t talk

What you see when it fails

Error: Error creating Instance:
  googleapi: Error 400: Invalid value
  for field 'resource.machineType'

# The plan passed. The apply failed.
# What did the agent assume?
# Which region did it pick? Why that type?
# Is there an org constraint it never knew?

# What the AI generated (6 weeks ago)
resource "google_compute_instance" "api" {
  machine_type = "e2-medium"   # "reasonable"
  zone         = "us-central1-a" # "default"
}

# What your org policy requires
# → only europe-west1, only n2-standard-*
# → the AI didn't know because you never wrote it down either

The pattern that repeats

With no explicit model

The AI invents plausible context. You assume it knows. It fails in prod.

With Stack Overflow

You copy code without understanding the assumption. At least you went looking.

With the AI

The agent generates with confidence. Confidence is contagious. So is the error.

The difference from Stack Overflow:
At least there you were actively searching.
With the AI, you delegate the search too.

Your project lives in your head

What lives only in your head

→

Why this service cannot have more than 3 replicas

→

What happened when we tried to scale in January, and why we failed

→

The tension between the platform team and the product team over who controls networking

→

Which alternative was rejected, and why

→

Which invariant cannot be violated without breaking the agreement with the security team

What lives only in your head cannot be validated.
An agent cannot consult it.
A new teammate cannot consult it.
You cannot consult it yourself in 6 months.

The README trap

# My Project

This service does X. It is deployed on GCP.
It uses Terraform. It has 3 environments: dev, staging, prod.

## Architecture
See diagram (out of date since March).

## Decisions
- We chose PostgreSQL because we didn't like MySQL.
- We use gRPC internally.

✗

It doesn't say what cannot change

✗

It captures neither the rejected alternatives nor the why

✗

It is not queryable or verifiable — it is prose

✗

It does not reflect the current state —
it reflects the state when it was written

The thesis

The ontology is not for the AI.

It is for you.

Formalizing invariants, tensions and current state
forces you to know what is true right now.

The AI benefits as a side effect.
It operates on what you already made clear.

The real value: the act of writing the ontology
is where YOU get clear, not the AI.

Ontology ≠ a list of decisions

A list of decisions

- We chose Kubernetes
- We use Helm for deployments
- PostgreSQL as the primary database
- gRPC between internal services
- OAuth2 for external authentication

Captures the what. It captures neither the why,
the rejected alternatives, nor the consequences.

An ontology

INVARIANTS

What cannot change without an explicit decision and coordination

ACTIVE TENSIONS

Trade-offs not yet resolved — they live in the system right now

CURRENT → DESIRED STATE

Maturity dimensions. Where you are, where you want to be, what blocks you

ACTIVE GATES

Conditions that must hold before crossing an architectural boundary

It is a queryable graph. Not prose.
The AI can read it. Your CI can verify it. You can reason about it.

Ontoref — three files, three questions

core.ncl

"What IS this project?"

axioms:
  - protocol-not-runtime
  - self-describing
  - sufficient-verification

tensions:
  - formalization vs
         adoption-friction
  - ontology vs reflection

practices:
  - ontology-three-file-split
  - adr-lifecycle

Immutable without a new ADR.

state.ncl

"Where ARE we?"

dimensions:
  protocol-maturity:
    current: protocol-stable
    desired: protocol-stable
    horizon: Months

  operational-mode:
    current: local
    desired: daemon
    catalyst:
         ontoref-daemon-boot

Evolves with the project.

gate.ncl

"When are we READY?"

membranes:
  protocol-adoption-gate:
    permeability: Low
    protocol: Observe
    active: true
    protects:
      - protocol stability
      - schema versioning

  content-vehicle-
        convergence:
    permeability: High
    protocol: Absorb
    active: true

Crossing conditions.

Typed Nickel · exportable as JSON · queryable from Nu · verifiable in CI

Reflection — what BECOMES

Ontology = what IS

→ Invariants — structural truth

→ Tensions — living trade-offs

→ State — where we are now

Reflection = what BECOMES

→ Operational modes — sequences with a DAG of dependencies

→ ADRs with typed constraints — living decisions, not prose

→ Structured backlog — tensions → tasks

→ Session history — who did what and when

The ontology captures being.
Reflection captures operating on that being.

A mode as an executable specification

# reflection/modes/new_service.ncl
{
  id      = "new_service",
  trigger = "When adding a new service boundary",
  steps   = [
    {
      id     = "draft-adr",
      actor  = "developer",
      action = "Draft ADR for service boundary decision",
    },
    {
      id         = "verify-invariants",
      actor      = "agent",
      action     = "Check no invariant is violated",
      depends_on = [{ step = "draft-adr" }],
    },
    {
      id         = "seal-config",
      actor      = "developer",
      action     = "Apply initial config seal",
      depends_on = [{ step = "verify-invariants" }],
    },
  ],
}

Not a runbook. A typed acyclic graph.
The AI executes it. The system validates it.

AI as an actor, not an oracle

With no formalized ontology

# What the agent receives
"Help me scale this service"

# What the agent assumes
- that it can add replicas freely
- that the current state is the desired one
- that there are no org constraints
- that December's decision is irrelevant

# What it generates
resource "google_compute_instance" {
  count = 5  # reasonable, right?
}

With a formalized ontology

# What the agent receives (SessionStart hook)
INVARIANT: max-replicas-per-zone = 2
TENSION: scaling vs consistency [unresolved]
CONSTRAINT (adr-003): no horizontal scaling
  without explicit capacity review
STATE: backend-maturity = single-stable
  → desired: multi-stable
  → blocker: capacity-review-pending

# What the agent can do
- Ask whether it is warranted given the blocker
- Generate the config within the limits
- Flag that the ADR must be reviewed first

The agent operates on what you already made clear.
It stops inventing context because you stopped keeping it implicit.

Who keeps this up to date?

The question that always comes up.

The real problem with the README

✗

Nobody has an incentive to update it —
it is not on the critical path

✗

There is no signal for when it is stale

✗

Updating it takes the friction of free-form writing

✗

There is no verification — it can diverge silently

Ontoref’s design

Pre-commit as enforced synchronization

nickel typecheck on every commit — the declarative layer is never left broken

Modes as mandatory procedures

Adding a service runs the mode — the ADR is written as part of the process

Drift detection

sha256(nickel export) — you know when the sealed state differs from the current one

ADRs as constraints, not prose

The constraint is machine-readable — CI can verify it, not just read it

The ontology stays current because it is the path.
Not because someone is disciplined.

For the discussion

Thread 1 — Ontology

Isn't a good README enough?

When was the last time yours was up to date?

What sets an ontology apart from a list of decisions?

Structure, queryability, verifiability.

Who maintains this when the project moves fast?

The design makes it mandatory, not optional.

Thread 2 — Infra + AI

Is it different from copying Stack Overflow?

On SO you searched. With the AI, you delegate the search too.

Where is the minimum understanding you need?

Knowing what cannot break. Without that, you have no control.

Do internal platforms solve this, or hide it?

A platform with no ontology just moves the ignorance one level up.

AI can declare your infra.

It cannot understand it for you.

The ontology is the model that forces you to know what is true now.
Reflection is the operation over that model.
The AI is the actor that operates on what you already made clear.

Thank you. Questions?

jesusperez.pro · ontoref.dev