documentation-and-adrs

Files (1)

• SKILL.md

SKILL.md (first lines)

# Documentation and ADRs

## Overview

Document decisions, not just code. The most valuable documentation captures the *why* — the context, constraints, and trade-offs that led to a decision. Code shows *what* was built; documentation explains *why it was built this way* and *what alternatives were considered*. This context is essential for future humans and agents working in the codebase.

## When to Use

- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API surface (the OpenAPI contract, an MCP `kb.*` tool, a `BotPolicy` field)
- Shipping a feature that changes a capability's behavior contract
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly

**When NOT to use:** Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.

## Architecture Decision Records (ADRs)

ADRs capture the reasoning behind significant technical decisions. They're the
highest-value documentation you can write.

**In this repo, OpenSpec change `design.md` files already serve as lightweight,
per-change ADRs** — they record the problem, the chosen approach, and rejected
alternatives for that change. This is where new decisions go.

This repo has **just replaced its RFC system with OpenSpec**. The former RFCs
(`docs/design/`) are being preserved as design rationale under `docs/design/NNNN-<slug>.md`,
linked from each capability's `## Purpose`, and **`openspec/specs/<capability>/spec.md`
is now the canonical source of truth** for current behavior. So:

- A decision scoped to **one change** → that change's `design.md`.
- A **durable, cross-cutting** decision future changes must respect → a doc under
  `docs/design/` (the former-RFC home), referenced from the relevant capability spec.

### When to Write a (durable) design doc / ADR under docs/design/

- A decision that constrains *future* OpenSpec changes (not just this one)
- Choosing a major dependency or boundary (`anthropic-sdk-python` directly — no
  LangChain/LangGraph; MCP as the internal tool boundary; `sentence-transformers`
  for local embeddings; MiniMax via the Anthropic-compatible endpoint)
- The multi-tenant data model and `tenant_id`-on-everything invariant
- The credential-encryption strategy (Fernet, `ingest_core.crypto`, decrypt
  server-side only)
- The retrieval-runtime / lobe-engine model (append-only versions, the compression
  invariant, `temperature == 0` on synthesize/cite/filter)
- The citations-mandatory / refuse contract
- Any decision that would be expensive to reverse

If a decision lives entirely within one change, capture it in that change's
`design.md` instead of a separate doc.

### Design-doc / ADR Template

Store durable design docs in `docs/design/` with sequential numbering (the
former-RFC convention):

```markdown
# 0007: Multi-tenant isolation keyed by tenant_id on every query and cache key

## Status
Accepted | Superseded by 00XX | Deprecated

## Date
2026-06-22

## Context
MeKnow is a multi-tenant RAG platform: many orgs share one deployment, and an
org must never see another org's documents, answers, or cache. Bolting tenancy on
per-feature would leak across joins and shared caches.

## Decision
Every table, query, cache key, and log line carries tenant_id. Cross-tenant joins
are bugs. Cache keys additionally include an ACL-cohort hash so two callers with
different KB permissions never share a cached answer. ACL is enforced server-side
inside retrieve_kb; the caller identity is inherited from the request, never
trusted from the model.

## Alternatives Considered

### Row-level security only, no tenant_id in cache keys
- Pros: DB enforces isolation at the row layer
- Cons: shared caches still leak across tenants/ACL cohorts
- Rejected: the cache is a real cross-tenant leak path; keys must be scoped

### Per-tenant database / schema
- Pros: hard isolation
- Cons: operationally heavy; breaks shared embeddings + golden-set tooling
- Rejected: tenant_id scoping gives the guarantee without the operational cost

## Consequences
- Cross-tenant isolation is gate-tested (benchmarks/gates/tenant-isolation-test.sh)
- Spec lives in openspec/specs/auth-and-tenancy/spec.md
```

### ADR / design-doc Lifecycle

```
PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)
```

- **Don't delete old design docs / RFCs.** They capture historical context — that's
  exactly why the former `docs/design/` are being preserved under `docs/design/`.
- When a decision changes, write a new doc that references and supersedes the old one.
- Cross-reference: link the doc from the relevant `openspec/specs/<capability>/spec.md`
  (`## Purpose`) and from the change `design.md` that introduced or revisited the decision.

## OpenSpec specs vs. design docs (this repo)

| Artifact | Captures | Lives in |
|---|---|---|
| `openspec/specs/<capability>/spec.md` | The *current* behavior contract (the source of truth) | `openspec/specs/` |
| change `design.md` | The reasoning for *this* change (a lightweight ADR) | `openspec/changes/<name>/design.md` |
| durable design doc (former RFC) | A cross-cutting decision future changes must respect | `docs/design/NNNN-<slug>.md` |

When behavior changes, update the spec via a change's delta + `/opsx:sync` — don't
let the spec drift from the code.

## Inline Documentation

From minhlucvan/emdesign, Apache-2.0.

More from minhlucvan/emdesign