sjat
8e4bf3dd88
Review O5/O6: ADR-006 mislabeled backend.tf as "Forgejo state backend" (its own State-backend section chooses local state — Forgejo's API is read-only); ADR-014 called plugin reproducibility open though TODO 10.7 is done. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
104 lines
5 KiB
Markdown
104 lines
5 KiB
Markdown
# 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 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.
|
|
|
|
See also: ADR-013 (heritage / translate-don't-transplant), ADR-011 (version pinning),
|
|
ADR-008 (testing/verification).
|