# ADR-014 — Sourcing technical knowledge (docs and best practices)

## Context

Most work in boma is done by AI agents drawing on training memory, which is stale
and hallucination-prone for version-specific facts. The repo **pins tool versions**
(`requirements.txt`, `requirements.yml`, image tags), so the right reference is the
docs for *our pinned version*, not "the latest." The capability to fetch
authoritative knowledge already exists (`context7`, `WebFetch`/`WebSearch`, the
`deep-research` skill, the `claude-code-guide` agent) but is ungoverned. This ADR
sets the policy for sourcing knowledge and translating it to boma's aims. (Resolves
TODO 10.4.)

## Two kinds of knowledge, two rules

- **Facts** — version-specific syntax, options, defaults, behaviour. There is one
  authoritative answer: the version-matched official docs. Training memory is the
  *draft*, never the authority.
- **Judgments** — "best practice," how to structure or approach something. External
  best practices are **evidence to translate through boma's principles**, never
  adopted because the docs or a blog say so. This extends ADR-013's
  translate-don't-transplant leash to all external sources: the acceptance test is
  *"can this be justified from boma's principles?"* — the source is the prompt, not
  the authority.

## When consulting is required (risk-based)

Routine, well-known syntax may rely on memory. Consulting a version-matched
authoritative source is **required** when any of these hold:

- it is **security-relevant**; or
- the tool is **unfamiliar or fast-moving**, or the version is **newer than the
  agent's training**; or
- the agent is about to assert a **specific flag/option/default it cannot quote with
  confidence**.

**Transparency backstop:** because "I'm uncertain" is an unreliable self-assessment
(agents are often confidently wrong), any version-specific claim given *from memory*
is marked **"from memory, unverified"** so it is visible and checkable. By the time
something is durable and version-specific, it has usually crossed a trigger and
should be verified, not left unverified.

## Source hierarchy

1. **Version-matched official docs** — `context7` for libraries/frameworks; upstream
   docs via `WebFetch` for tools. Match the pinned version.
2. **Claude Code / SDK / API questions** → the `claude-code-guide` agent.
3. **Broad or contested questions** → the `deep-research` skill (multi-source,
   fact-checked).
4. Reputable references below those. **Training memory is never the authority** for a
   version-specific fact.

Cite the source whenever one is consulted.

**Graceful degradation:** `context7` and the agents/skills above are *plugins* and may
be absent on a fresh checkout (see "Reproducibility" below). The always-available
fallback is `WebFetch`/`WebSearch` (core tools). This policy commits to the
**principle** — consult version-matched authoritative docs and cite — never to a
specific plugin, so it holds on a bare install.

## Capture (hybrid)

- **Facts** that can go stale get a durable, greppable stamp next to the fact (a
  comment in the role/template, or a line in an ADR):

  ```
  verified: <subject> · <tool> <version> · <source> · <YYYY-MM-DD>
  ```

  This makes currency trackable and gives re-verification a trigger.
- **Judgments** follow ADR-013: translated to boma's terms, durable docs stay clean,
  lineage stays transient (commit/conversation).

## Re-verification

A stamp binds a fact to a **pinned version**. When that version bumps (a
`requirements` change or an image upgrade), the stamps for that tool mark exactly
what to re-check. A future `/review-repo` or `/security-review` check could flag
stamps whose recorded version no longer matches what is pinned (stale-stamp
detection) — a noted enhancement, not built yet.

## Reproducibility of the toolchain

The accelerators this policy prefers (`context7`, `deep-research`, `superpowers`,
`claude-code-guide`) are **plugins under `~/.claude/`** — local per machine, **not**
synced by Claude account and **not** carried by the git repo (only `.claude/commands`,
`.claude/hooks`, `.claude/settings.json` travel). A fresh clone therefore lacks the
plugin toolchain until it is reinstalled. Making it reproducible from the repo
(`extraKnownMarketplaces` + `enabledPlugins` in `.claude/settings.json`, plus a
bootstrap step) is tracked in `docs/TODO.md` and tied to control-node/AI setup. Until
then, the graceful-degradation fallback above keeps the policy working.

## Decision

- Distinguish **facts** (consult version-matched authoritative docs; cite; stamp) from
  **judgments** (translate through boma's principles per ADR-013; never authority).
- Require consultation **risk-based** (security / unfamiliar-or-fast-moving / can't
  quote with confidence), with a from-memory transparency backstop.
- Commit to the principle, not a tool — degrade to `WebFetch`/`WebSearch` when plugins
  are absent.

See also: ADR-013 (heritage / translate-don't-transplant), ADR-011 (version pinning),
ADR-008 (testing/verification).