WRIT Docs

#What is WRIT?

WRIT is a system for detecting misalignment — the gap between what people expect to be true and what is actually true in their organisations.

Every organisation operates on assumptions: "all IT services have an assigned owner", "every employee has completed security training", "all production namespaces have a backup policy". When these assumptions break silently, the consequences range from compliance failures to operational outages.

WRIT makes these assumptions explicit by turning them into expectations — formal statements about what should be true — and then continuously evaluating them against real-world data using three-valued logic (true, false, or unknown).

#How It Works

WRIT follows a pipeline that moves from human intent to actionable insight:

  1. Expectations — A person (the expector) states what they want to be true. For example: "All IT services must have an assigned owner."
  2. Domain models — Entity types (IT services, people, teams) are defined with their attributes and relationships, forming a structured vocabulary.
  3. Attestation — Data is collected from real sources (spreadsheets, APIs, databases) as evidence of what is currently true.
  4. Evaluation — WRIT evaluates each expectation against the attested data. Because real data is often incomplete, the result is not just true or false but one of three values: true, false, or unknown.
  5. Questions and actions — Where data is missing, WRIT generates questions directed at the people who can provide the data. Where expectations are not met, it generates actions directed at the people responsible for fixing the situation.

#Why Three-Valued Logic?

Traditional systems treat missing data as either an error or a default value. WRIT treats it as what it is: unknown. This matters because:

  • An IT service with no owner assigned is a false — the expectation is definitely not met, and someone needs to fix it.
  • An IT service whose owner field was never collected is unknown — we cannot say whether the expectation is met until the data is gathered.
  • An employee referencing a department that does not exist is void — the relationship is structurally impossible, not just missing.

These three cases require different responses (action, question, or structural fix), and conflating them leads to wrong priorities and wasted effort.

#Key Components

Component What It Does
kbpy The knowledge base engine. Defines domain models, evaluates expectations, and produces questions and actions. Uses a custom DSL for defining domains.
writ-kb The web application. Visualises domain state, expectations, and evaluation results through a Remix-based UI.
Proxy Handles data ingestion from external sources.
Transactor Manages the persistence layer for domain state.

This documentation covers kbpy and writ-kb. The proxy and transactor are documented separately.

#Next Steps