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

StatusMeaning
proposedUnder discussion
acceptedDecision approved and in effect
deprecatedNo longer recommended
supersededReplaced by another ADR

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

The 12 ADRs

MIF’s 12 ADRs span three themes:

Type system and content model (ADR-001 through ADR-006): the cognitive-triad taxonomy, dual-format design, Obsidian compatibility, 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.