Methodology signature

The Four-State Model: Evidenced, Inferred, Missing, Conflicting

Architecture documents lie, but not deliberately. They lie because the format forces them to.

Take any HLD ever written. Every sentence in it is phrased as a confident declarative. "The payments service writes to the user database." "The API gateway handles authentication." "The queue is sharded by customer ID." Every claim gets the same grammatical weight, whether it was pulled from a verified DDL statement, inferred from a team member's memory, or made up by the person writing the document at 11pm the night before review.

The reader has no way to tell the difference. Neither does the auditor. Neither does the next architect who inherits the system.

The four-state model fixes this by refusing to let claims lie flat.

The four states

Every architectural claim — every relationship, every property, every capability — exists in one of four states:

✓ Evidenced — a source says this, and the source is cited. You can click the claim and land on the line of the OpenAPI spec, the DDL statement, the Terraform resource, the code file, or the runtime trace that proves it.

~ Inferred — the model believes this based on other evidence, but no source directly asserts it. The inference is captured with its reasoning. Example: if the DDL shows a foreign key from orders.user_id to users.id, the claim "orders service depends on users service" may be inferred, not evidenced, because no single source states the service-level dependency directly.

? Missing — we know we don't know. The gap is explicit. The document does not silently pretend the claim is true; it names the hole. Example: if no source mentions authentication on the reporting endpoint, the AIP does not default to "no auth." It emits auth: missing, and a reviewer has to decide whether to investigate or accept the gap.

⚠ Conflicting — two sources disagree. Both are preserved. Example: the OpenAPI spec says the endpoint returns 200 on success; the code returns 204. The model doesn't pick a winner. It surfaces the conflict until a human resolves it.

Why this beats the alternative

The alternative, in 99% of enterprise documentation, is a two-state model: "stated" and "not stated." Everything stated is presented as equally confident. Everything not stated is absent — as if it doesn't exist.

This is catastrophic in three ways.

First, it collapses the confidence hierarchy. A claim backed by a parsed DDL gets the same visual weight as a claim someone half-remembered from a meeting. A senior architect reviewing the doc has no way to allocate their attention.

Second, it hides gaps. "Not stated" and "does not exist" look identical. Auditors cannot tell whether a control is absent or just undocumented. This is exactly the ambiguity that blows up audits.

Third, it silently picks winners in conflicts. When two sources disagree, whichever one the author saw most recently wins. The other disappears. Six months later, the architecture drifts toward whichever was wrong.

The four-state model treats each of these pathologies as the data-modelling problem it actually is.

What it looks like in practice

A generated HLD paragraph under the four-state model doesn't read as a flat declarative. It reads like this:

The payments service authenticates requests via OAuth2 [evidenced: openapi/payments.yaml:142]. It writes to the payments_ledger table [evidenced: terraform/rds.tf:88], which is [inferred: shared schema with reconciliation service, based on DDL foreign key reconciliation.ledger_id → payments_ledger.id]. The retention policy on payments_ledger is [missing: no source specifies retention; compliance requires review]. The queue shard key is [conflicting: README.md says customer_id; terraform/sqs.tf says tenant_id].

A human reader can read this in 20 seconds and know exactly what's solid, what's guessed, what's absent, and what needs resolving. An auditor can read it and stop treating the document as opaque.

The compliance angle

Every serious compliance framework — SOC 2, ISO 27001, PCI-DSS, NIST 800-53, EU AI Act — has a provenance requirement somewhere in it. The language varies, but the demand is the same: you must be able to show where a claim came from and how you verified it.

The two-state documentation model cannot satisfy this. It has no structural place to put evidence. Teams end up maintaining a separate "evidence spreadsheet" alongside the document, which diverges from the document immediately and is useless by the next audit.

The four-state model puts evidence inside the claim. Provenance is not a separate artifact; it is a property of every sentence. This is the only structure that scales through an audit without turning the architecture team into a full-time evidence-gathering operation.

The cultural angle

There is also an under-discussed benefit: the four-state model gives teams permission to not know things.

In most engineering cultures, "I don't know" is culturally expensive. Architects paper over gaps with plausible-sounding sentences because the alternative — writing "unknown" in a formal document — feels like an admission of failure. Over years, this produces architecture documentation that is 80% confident and 20% honest, in unpredictable proportions.

When "missing" is a first-class state, admitting a gap becomes a structural affordance instead of a career risk. Teams surface what they don't know. Reviewers allocate attention to real gaps. The documentation gets more honest, faster.

What this means if you're evaluating an AI architecture tool

One question cuts through the demo:

"Show me how the system represents a fact where two source documents disagree."

If the answer is "it picks whichever is more recent" — walk away.If the answer is "it averages them" or "the LLM resolves it" — walk away faster.If the answer is "both are preserved and the claim is marked conflicting until a human reviews it" — you are talking to a real system.

The bigger bet

The four-state model is a wager about where architecture documentation is heading. The bet is that in five years, the documents that survive will not be the ones that look most confident. They will be the ones that are most honest about what they know, what they guessed, and what they don't.

Confidence is cheap. Evidence is what scales.

Want to see the four-state model on one of your own products? Book a 20-minute demo →