Skip to content
MIF

Design Rationale

MIF’s design is documented through Architecture Decision Records (ADRs). This page explains why ADRs matter for MIF and how they are structured.

Why ADRs?

MIF makes opinionated choices: a cognitive-triad type system, markdown-canonical with derived JSON-LD, pinned OKF compliance, a configurable decay model. Each of these choices has a reason, a set of alternatives considered, and consequences that ripple through the format.

ADRs capture that reasoning in a form that:

  • Explains why a design exists, not just what it is
  • Documents the alternatives that were evaluated and rejected
  • Records the trade-offs that were consciously accepted
  • Provides an audit trail as the spec evolves

When MIF’s design surprises you, the ADRs should explain it.

Structured MADR format

MIF uses the Structured MADR format — an extension of MADR (Markdown Architectural Decision Records) that adds:

  • YAML frontmatter for machine-readable status, date, and relationships
  • Full risk-assessed option analysis for each considered alternative
  • Split Positive/Negative/Neutral consequences instead of a single list
  • A required Audit section with code-grounded citations (file:line anchors)

The Audit section is the distinguishing feature: it ties the ADR’s claims back to the codebase. A finding that cannot be verified in code is flagged Status: Pending rather than asserted.

ADR status values

Status Meaning
proposed Under discussion
accepted Decision approved and in effect
deprecated No longer recommended
superseded Replaced by another ADR

An amended decision keeps status: accepted and documents the change in an ## Amendment section (see ADR-007).

The ADRs on this site

ADR-001 through ADR-012, mirrored on this site, span three themes:

Type system and content model (ADR-001 through ADR-006): the cognitive-triad taxonomy, dual-format design, Obsidian compatibility (since superseded by ADR-017, which reverted the Obsidian-specific conventions), three-tier trait inheritance, namespace prefix convention, and entity representation.

Schema and identity (ADR-007, ADR-008): schema $id strategy (amended to mif-spec.dev) and the temporal decay model.

OKF compliance and specification governance (ADR-009 through ADR-012): MIF as a superset of OKF, the repositioning to a general content model, markdown-canonical primacy, and OKF conformance as a tested CI invariant.

Browse them in the Architecture Decision Records section.

Later decisions, ADR-013 through ADR-021, cover provenance, document references, attested releases, versioned schema mirrors, the revert of Obsidian compatibility, the ontology corpus, entity-type classification, and the container profile. They live in the MIF repository and are listed in the ADR index.