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.