boma/docs/decisions/014-knowledge-sourcing.md

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

## Status

Accepted (2026-06-04)

## 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 is
**done** (TODO 10.7): `.claude/settings.json` declares `extraKnownMarketplaces` +
`enabledPlugins`, and `docs/runbooks/claude-code-setup.md` documents the per-machine
bootstrap. Until a fresh clone runs that bootstrap, 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.

## Consequences

Drawn from the follow-on work and limitations this ADR already states:

- Verified facts carry a durable, greppable stamp; a stamp binds a fact to a pinned
  version, so a `requirements` change or image upgrade marks exactly what to re-check
  (per Capture / Re-verification).
- Stale-stamp detection — a `/review-repo` or `/security-review` check flagging stamps
  whose recorded version no longer matches what is pinned — is a noted enhancement, not
  built yet (per Re-verification).
- Any version-specific claim given from memory must be marked "from memory, unverified"
  as a transparency backstop, since agent self-assessed certainty is unreliable (per
  When consulting is required).
- The policy commits to the principle rather than a specific plugin, so it degrades to
  `WebFetch`/`WebSearch` on a bare install; reproducing the plugin toolchain from the
  repo is done via `.claude/settings.json` and `docs/runbooks/claude-code-setup.md`,
  with the graceful-degradation fallback covering a fresh clone until bootstrap runs
  (per Source hierarchy / Reproducibility of the toolchain).

## Related

- ADR-013 — heritage / translate-don't-transplant.
- ADR-011 — version pinning.
- ADR-008 — testing / verification.