Architecture Decision Records (ADRs)

Reference documentation for Architecture Decision Records (ADRs) in Adaptive Skills.

This directory holds durable architectural decisions for Adaptive Skills. ADRs are written when a decision is hard to reverse, affects multiple parts of the library, or settles a recurring ambiguity that has cost time to re-litigate.

What an ADR is — and is not

• Is: a record of why we decided something at a specific date, with the alternatives we rejected and the conditions that would reopen the decision.
• Is not: a tutorial, a roadmap, or a contract spec. Those live in docs/concepts/, ROADMAP_EVOLUTIVO.md, and the skill model docs.

If a document explains how to do something, it is a guide. If it specifies what must be true, it is a contract. ADRs answer why this path and not another.

Convention

• Format: lightweight, repo-native. Mirrors the AletheIA repo convention for cross-repo consistency.
• Filename: ADR-NNN-<kebab-case-title>.md, with NNN zero-padded.
• Numbering: monotonic, never reused. If an ADR is superseded, the new ADR gets the next number and links back via the Supersedes field.
• Status values: Proposed, Accepted, Superseded by ADR-XXX, Rejected, Deprecated.
• Length: prefer ≤2 pages. If an ADR grows past that, the decision is probably mixing two concerns.

Required structure

Every ADR starts with a metadata table:

| Field | Value |
|---|---|
| Status | Accepted |
| Date | YYYY-MM-DD |
| Author | <name> |
| Deciders | <names> |
| Related | ADR-XXX — <title> |
| Supersedes | — or ADR-XXX |

Followed by numbered sections:

1. Context — what is the state of the world and what is the open question.
2. Decision — what we decided, in normative voice.
3. Consequences — positive, negative, and accepted tradeoffs.
4. Alternatives considered — what we rejected and why.
5. Relationship — to other ADRs, phases, or artifacts that depend on this decision.
6. Review — conditions that would reopen the ADR.

Current ADRs