Decision Log

Decision Log

Architectural decisions that shaped domus-captures, with rationale. Each entry records what was decided and why — the reasoning matters more than the choice.

2025-01: Antora over Hugo/MkDocs

Multi-repo aggregation was the deciding factor.

  • Hugo — single repository. Cannot aggregate 15 independently maintained repos into one site.

  • MkDocs — single repository. Same limitation.

  • Antora — 15 repos become one site. Each spoke has its own lifecycle, CI, and ownership.

For a 15-spoke ecosystem, Antora was the only viable choice.

2025-01: AsciiDoc over Markdown

Richer semantic markup: admonitions, complex tables, includes, cross-references, and attributes.

Markdown cannot do:

  • Cross-component references (component::page.adoc)

  • Conditional includes

  • Attribute substitution in code blocks (subs=attributes+)

  • Partials with single-source-of-truth composition

AsciiDoc is the documentation standard for enterprise technical writing. The tradeoff is a steeper learning curve, which is acceptable for a system built to last.

2026-03: Partial+Page Pattern

Content lives in partials; pages are 6-line shells with a single include:: directive.

This enables:

  • Composability — include the same partial in multiple pages

  • Single source of truth — one file, one fact

  • Separation of content from metadata — the partial has content, the page has header attributes

Inspired by the ThinkPad P16g restructure which proved the pattern at scale (27 files, 13 phases, 7 appendices).

2026-03: Aristotelian Taxonomy

Techne / Episteme / Phronesis / Poiesis organizes knowledge by how it is known, not what it is about.

A networking pattern and a vim pattern share the same Techne structure because they are both craft knowledge. A security incident and a DNS outage share the same Phronesis structure because they are both experiential judgment.

This prevents the "where does it go?" problem that plagues topic-based taxonomies.

2026-04: Standards Framework (RFC 2119)

Patterns are descriptive; standards are prescriptive.

When a pattern proves non-negotiable across contexts, it graduates to a standard. RFC 2119 keywords (MUST / SHOULD / MAY) remove ambiguity about what is required versus recommended.

20 standards were created in a single session, codifying rules that already existed implicitly.

2026-04: Feature-Based over Phased for domus-captures

domus-captures is an evolving system, not a sequential deployment.

Features (architecture, standards, content, nav, build, AI, education, projects) are independently developed and maintained. A phased archetype would imply a linear build order that does not exist — there is no "Phase 3" that must complete before "Phase 4."

2026-04: Everything Is a Project

Random notes rot. Projects have structure, status, and accountability.

The /capture-idea skill scaffolds STD-001-compliant projects from raw thoughts. Even domus-captures itself became a project documenting itself — proving the model is self-consistent.