Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Architecture Knowledge Base Taxonomy

ADR-26035: Architecture Knowledge Base Taxonomy

Date

2026-02-26

Status

accepted

Context

Research and analytical artifacts — dialogue transcripts, trade studies, analytical summaries — that support architectural decisions have no formal home in the repository. They end up scattered across misc/ or deleted entirely. This wastes architectural knowledge and makes it impossible for future engineers (human or AI) to trace how and why decisions were made.

The existing ADR system (ADR-26016) handles decisions well. Post-mortems handle failure analysis. But the upstream research pipeline — the dialogues and analyses that produce those decisions — is undocumented and unmanaged. There is a gap between “we had a conversation” and “here is the ADR.”

The Problem in ISO 42010 Terms

ISO/IEC/IEEE 42010 defines an Architecture Knowledge Base as the combination of architectural decisions, their rationale, and the evidence that supports them. Our repository captures decisions (ADRs) but discards evidence. This violates the standard’s intent: decisions without traceable evidence become opaque assertions.

Current State

Artifact typeCurrent locationStatus
ADRsarchitecture/adr/Managed (ADR-26016, ADR-26017)
Post-mortemsarchitecture/post-mortems/Partially managed, no frontmatter
Analysesmisc/ or deletedUnmanaged
TranscriptsNot committedLost

Decision

Adopt a three-category Architecture Knowledge Base taxonomy aligned with ISO 42010, formalized as a directory structure and machine-readable configuration.

1. Conceptual Taxonomy

Architecture Knowledge Base
├── Decisions        → ADRs (binding constraints)
├── Evidence
│   ├── Prospective  → Analyses, trade studies, comparisons
│   ├── Retrospective→ Post-mortems, failure analyses
│   └── Sources      → Dialogues, transcripts (ephemeral)
└── Governance       → Manifesto, guides, config

2. Physical Directory Structure

architecture/
├── evidence/
│   ├── analyses/           # A-YYNNN_slug.md
│   ├── retrospective/      # R-YYNNN_slug.md
│   └── sources/            # S-YYNNN_slug.md (ephemeral)
│       └── README.md       # Permanent: explains git archaeology
└── ...                     # Existing directories unchanged

3. Namespace Convention

Each artifact type gets an independent ID namespace with a year prefix:

TypePrefixPatternExample
AnalysisAA-YYNNNA-26001
RetrospectiveRR-YYNNNR-26001
SourceSS-YYNNNS-26001
Decision (ADR)ADRADR-NNNNNADR-26035

Rationale: One analysis can produce many ADRs (1:many mapping), so analyses need independent IDs. Year prefix (YY) makes artifact age visible from the filename.

4. Frontmatter Schemas

All schemas are defined in the evidence validation config in .vadocs/ (the single source of truth, see ADR-26036). Tags are inherited from the shared governance config — no duplication. The ADR establishes the principle; the config is the living specification that can evolve without amending this ADR.

Analysis (evidence/analyses/A-YYNNN_slug.md):

---
title: Architecture Knowledge Base Taxonomy
date: 2026-02-26
tags:
- governance
- documentation
options:
  id: A-26001
  status: active
  sources:
  - S-26001
  produces:
  - ADR-26035
  type: adr
  token_size: 2218
---

Retrospective (evidence/retrospective/R-YYNNN_slug.md):

---
id: R-26001
title: "SLM Non-Determinism in Commit Generation"
date: 2026-02-01
status: active          # active | resolved | superseded
severity: high          # low | medium | high | critical
tags: [ci, model]
produces: [ADR-26003]
---

Source (evidence/sources/S-YYNNN_slug.md):

---
id: S-26001
title: "Claude — AKB Taxonomy Discussion"
date: 2026-02-26
model: claude-opus-4     # AI model or "human" for meeting notes
extracted_into: A-26001  # null until analysis exists
---

5. Source Lifecycle (Three-Commit Workflow)

Sources are ephemeral by design — committed for traceability, deleted after extraction:

  1. Commit 1 — Capture: Add transcript to evidence/sources/S-YYNNN_slug.md

  2. Commit 2 — Extract: Write analysis to evidence/analyses/A-YYNNN_slug.md with sources: [S-YYNNN]. Update source’s extracted_into field.

  3. Commit 3 — Delete: Remove the source file. Git history preserves it.

Rule: A source file is only deleted AFTER its extracted_into field points to a committed analysis.

Git archaeology commands for recovering deleted sources are documented in evidence/sources/README.

6. Validation

check_evidence.py validates evidence artifacts against the .vadocs/ evidence config, following the same pattern as check_adr.py validates ADRs (ADR-26017).

Validation covers:

7. Portability

This taxonomy is designed to be adoptable by any repository:

  1. Copy the .vadocs/ evidence config and check_evidence.py — adapt tags and sections to your domain

  2. Create the evidence/ directory structure

  3. (Optional) Add pre-commit hook and CI job

The conceptual taxonomy (Decisions / Evidence / Governance) is universal. The physical structure and tooling are the reference implementation.

Consequences

Positive

Negative / Risks

Alternatives

References

Participants

  1. Vadim Rudakov

  2. Claude (AI Systems Architect)

Adr
ADR-26034: Agentic OS Paradigm: Skills as Composable Applications
Adr
ADR-26036: Config File Location and Naming Conventions