Authentic Ignorance

How State Works

A plain explanation of how State behaves: what it enforces, who has authority to do what, and what happens when something goes wrong. This assumes you already know why State exists. For that, read the case study first.

Depth Product behavior, not source codeBest for Product, engineering, and technical reviewersStatus Working prototype, not in production use
Overview

State maintains a current, versioned understanding of a project.

New projects first build a Starting State from existing project material; after that, the same Evidence → Review → Current State model keeps that understanding up to date.

The system model

Evidence comes in. AI interprets it. A person decides what becomes authoritative.

Something happens
Evidence
AI interprets
Review
Human decision
Current State

A Review is where a person decides whether an AI interpretation should affect the maintained project understanding. Some Reviews propose a Current State change; others raise a Question instead, a known unknown the team tracks rather than resolves immediately. Ask sits outside the decision loop and reads across the maintained context.

Core objects

Six objects, each with one job.

Evidence
The immutable record of what was said, observed, or submitted.
Current State
What the project currently treats as true.
Review
A consequential interpretation waiting for human judgment.
Question
A known unknown being tracked, optionally marked blocking.
History
The record of actual Current State transitions.
Ask
A read-only way to use the maintained context.
Authority

AI interprets → Software enforces → People authorize.

AI
  • Interprets Evidence
  • Proposes consequential interpretations
  • Synthesizes Ask responses
Software
  • Validates structure and semantics
  • Enforces authority rules
  • Blocks stale writes
  • Handles deterministic deduplication
  • Applies atomic State transitions
People
  • Decide whether Current State changes
  • Decide whether a Question is created or resolved
  • Can adjust wording before authorizing anything
AI cannot change Current State. A human-authorized Review is the only write path.
Starting a project

Starting State builds the first trustworthy project picture.

A new user-created project begins in Baseline Setup. A person can add existing project material or enter what they already know, and State uses that material to propose a Starting State through the normal Evidence and Review flow. During setup, the AI looks for broad baseline coverage while unresolved unknowns stay Questions.

During setup, State tries to preserve useful source structure, group durable facts into a small set of sensible areas and topics, and split independently maintainable facts instead of collapsing a whole document into one summary. Large sources can be interpreted in bounded pieces while the original Evidence remains intact. Setup can finish only after pending Reviews are resolved and failed or unfinished Evidence is cleared, then a person explicitly finishes the baseline.

Evidence

Preserved input, not automatically truth.

Evidence is the preserved record of what came in. It may come from a manual Note, a supported uploaded document, or an approved Slack channel. Once created, it's immutable, and a correction becomes new Evidence rather than rewriting the old record.

Evidence isn't automatically treated as true. If State initially decides it does not need a Review, a person can ask State to reconsider it. Reconsideration reruns interpretation and may surface a Review.

Reviews

The decision boundary between interpretation and authority.

State creates a Review when new Evidence looks consequential. Depending on the situation, a Review may propose changing Current State, creating or resolving a Question, or leaving Current State unchanged. The person reviewing it can:

  • Update Current State: accept the proposed change.
  • Adjust, then update: change the wording before authorizing it.
  • Leave Current State unchanged: preserve the Evidence without changing the maintained truth.
  • Keep tracking uncertainty: create or link a Question instead of changing State.
  • Create a Question: authorize a suggested Question.
  • Dismiss: resolve the Review without applying the proposed outcome.

Pending proposals can also go stale or get superseded. A proposal is stale when its target State item has changed since interpretation, and accepting it is blocked. A proposal is superseded when newer Evidence updates the same Review and target with a replacement, so the older pending version is dropped in favor of the new one, not left open alongside it. Multiple proposals bundled into one Review are currently decided together, not one at a time.

Questions

Tracking what isn't known yet, not what's wrong.

Questions track known unknowns. They start open and can also be marked blocking, when the uncertainty should stop related work from moving forward.

Reviewed Evidence can resolve a Question without changing Current State. A flagged uncertainty about an existing fact can instead create or link a Question when that uncertainty should stay visible rather than be resolved outright. Questions can also be stopped manually when they're no longer worth tracking. To avoid duplicates, State compares a new Question's normalized text for an exact match against open Questions; it does not use fuzzy or semantic matching.

One caveat worth knowing: if a person materially changes the proposed wording before accepting it, any Question that Evidence was meant to answer stays open rather than being treated as silently resolved.

Current State and History

What's true now, and how it got there.

Current State is the maintained answer to what the project treats as true right now. Each item is versioned. If an update was based on an older version of that item, State rejects it rather than overwriting a decision made in the meantime.

History explains how that understanding changed. When an accepted Review actually produces a Current State transition, State records the before and after, along with why and from what source.

Not every accepted Review creates History. History is written only when Current State actually changes.

Ask

Reads across State. Changes nothing.

Ask synthesizes accepted Current State, pending Reviews, open Questions, and relevant Evidence and History to answer questions about the project. It keeps established facts, pending decisions, and unresolved Questions distinct rather than flattening them into one summary.

It has no write path into Current State, Reviews, or Questions. A query that reads like an instruction is redirected into the Evidence workflow instead of being executed as a command. The interface can stream answers and continue with follow-up questions.

Failure handling

What happens when something goes wrong.

State checks more than whether model output has the expected shape. Structured output must also pass semantic checks before it reaches the product. If the AI provider fails or times out, the request fails closed with an error rather than guessing at an answer. Unsupported or unreadable uploads, including scanned PDFs with no extractable text, also fail clearly instead of creating empty Evidence.

Testing and evals

Tested as software and as an AI product.

  • Deterministic tests: authority, versioning, validation, project isolation, and response shape.
  • Realistic QA: messy, ambiguous, real-shaped input.
  • AI evals: grounding, consequentiality, and review behavior checked against expected outcomes.

See docs/evals/ for the eval registry and state-project-complete/eval/ for the executable code.

Known limitations

Current, documented limits.

  • No multi-user roles or permissions
  • Not load-tested at real team scale
  • User-created project data is not yet durable across backend redeploys on the portfolio deployment
  • A known slow query pattern affects project switching under Postgres
  • Project areas aren't fully scoped per project at the schema level yet
  • Ask's generated prose occasionally has minor grammar issues
Go deeper

Case study, product, and source.