How Knowledge Works

A recorded choice with its context, reasoning, and author. Some decisions produce rules or constraints. Others are one-time actions or state changes - switching cloud providers, a technical choice for a specific case, a response to an incident. In all cases, the decision is an immutable historical fact: it documents what was decided, not what should be done next. If a decision needs to be revised, it can be superseded by a new decision linked to the original.

{
  "decision": "Use PostgreSQL for all transactional data stores",
  "context": "Evaluated PostgreSQL, DynamoDB, and CockroachDB",
  "reasoning": "ACID guarantees without distributed complexity",
  "author": "sarah.chen",
  "tags": ["database", "infrastructure"]
}

Knowledge does not block the creation of contradictory decisions - they are historical facts, recorded as-is. But a coherence check (on-demand or nightly) detects tensions and duplicates via semantic similarity, with actions to resolve each finding.

An absolute constraint - something that must never be violated. Invariants are blocking: if an action conflicts with an invariant, the action is stopped. Invariants are immutable like decisions. If a constraint needs to evolve, the current invariant is archived and a new invariant supersedes it via an explicit link. The old one remains available for audit. For exceptional cases, an override allows a temporary deviation without modifying the invariant itself.

"What must never happen?"

{
  "constraint": "All public API endpoints must require authentication",
  "rationale": "Security baseline - no exceptions without explicit approval",
  "requires_approval": true
}

An active directive - something that should be followed. Rules are versioned: when requirements change, a new version is created while the history is preserved. Two severity levels: Mandatory (must be followed; violations block CI checks) and Advisory (should be followed; violations generate warnings).

"What should we do?"

{
  "directive": "All PRs must be reviewed by at least one team member",
  "severity": "MANDATORY"
}

A governed exception - an explicit, approved deviation from a rule or invariant. Overrides are not workarounds. They are documented proof that the organization acknowledged a constraint, decided to deviate, and recorded why.

{
  "target": "rule:rul-9c2a",
  "justification": "Legacy payment gateway requires REST - gRPC migration planned for Q3",
  "conditions": "Applies only to payment-gateway-v2 service",
  "expires": "2026-09-30",
  "approved_by": "sarah.chen"
}

An override cannot be modified - it can be revoked and recreated if conditions change.