<!--
  scaffold: knowledge-retrieval-discipline.md
  bucket: knowledge-memory (Bucket 4)
  what belongs here: how the PA finds information.
    - pa knowledge verbs.
    - Repo-as-truth; memory-as-cache.
    - Verify-remembered-facts-via-retrieval-first pattern.
    - The Librarian sweeps staging; don't route observations directly.
-->

# Knowledge retrieval discipline

## The verbs

`pa knowledge` queries the operator's knowledge graph. Five verbs:

| Verb | Purpose |
|---|---|
| `pa knowledge related <slug>` | 1-hop neighbourhood for a doc. `--in` / `--out` limits direction. |
| `pa knowledge search <term>` | Text search across the knowledge tree. `--full` includes doc body. |
| `pa knowledge domain <name>` | Everything in a domain. |
| `pa knowledge orphans` | Docs with no incoming or outgoing links. Cleanup or new-link-add candidates. |
| `pa knowledge path <a> <b>` | Shortest link path between two docs. |

Add `--format json` when the output feeds another tool or role (e.g. the Briefer consumes JSON).

## Repo is single source of truth

Markdown for human-readable content. JSON for machine-readable indexes. Everything else is a cache — the desk overview, your model memory, `.session/environment.json`, all cache. The truth is on disk.

**When memory conflicts with current file state, trust current state and update the memory.** A memory that names a file, function, or flag is a claim from when it was written; the graph tells you if it's still current.

## Verify remembered facts

Before answering an important question from memory, verify.

1. Run `pa knowledge search <term>` (or `related`) to locate the doc that owns the fact.
2. Read the specific file for the specific claim.
3. Answer from what you just read.

Walking the filesystem directly (find, grep) bypasses the graph and misses cross-references. `pa knowledge` first, then targeted `Read`.

## Retrieval first, then read at the right size

The point of the retrieval CLI is not to skip reading; it is to read at the right SIZE. Whole-file reads are appropriate for:

- A doc under ~200 lines where the question spans its whole argument.
- A doc about to be edited (structural context matters for a good edit).
- A canonical reference (schema, role definition, standard) whose whole content is load-bearing.

For everything else — answering a factual question, checking a rule, resolving a reference from a brief — extract a snippet.

## Outward retrieval — `/research`

`pa knowledge` retrieves what the operator's estate already knows. When the answer is
**not** in the library — a fact about the outside world, current library/tool versions,
a comparison, a landscape survey — the default outward move is the **`/research`**
command, not ad-hoc web searching. It is one engine with three tiers:

- **light** — a single-hop fact-find, run inline (3–10 tool calls, no decomposition).
- **normal** — a 2–4 sub-question comparison/brief, run as a workflow (plan → search →
  extract → verify → deepen → synthesize).
- **deep** — an open-ended multi-facet sweep (4–12 facets, judged synthesis).

Every run persists a **session** (manifest, findings, sources, answer) so the research
leaves a durable trail and the durable answer can be promoted back into the library.

**Cost gate.** `/research` auto-triggered after a failed local lookup defaults to
**light**. **NORMAL and DEEP are never automatic** — they require prior operator
agreement, and deep additionally requires a per-run draft-plan confirm (facets + cost
estimate) before it dispatches. Expensive breadth is always a deliberate choice.

**Displacement — do not use the built-in `deep-research` skill/workflow.** `/research`
covers its use cases and adds what the built-in lacks: it persists the session,
promotes durable answers into the library, handles gated sources (login/paywall/
captcha) via an explicit gate policy, and pins the right model per stage. Reaching for
the built-in deep-research bypasses all of that and leaves no trail. Ad-hoc `WebSearch`
is a *fallback* for a one-off check, not the first move.

## REMOTE mode

The scaffold describes SIMPLE mode as the default: `pa knowledge` reads from on-disk markdown and JSON that live in the same working copy you edit. REMOTE mode (set by `library.mode: "remote"` in `operator/config/preferences.json`, plus `library.remoteEndpoint` and `library.remoteKey`) swaps the write path for the remote-library service: the retrieval surface pointed to by `pa knowledge` is a pulled read-only projection of the service's git repos, under `LIBRARY_PULL_CLONES_ROOT` (env) or `~/stravica-library-clones/` by default. Reads stay a filesystem call against that projection; writes go through the `library` CLI (`library put` for one event, `library flush` for the staging dir), never a direct edit of a clone. `pa knowledge context` prints which mode is live for the session. See `packages/library-cli/README.md` for verbs, flags and the vault-free help seam.

## Don't route observations directly

The Librarian sweeps staging during distillation. Each agent stages observations to its own staging dir; the Librarian routes them to canonical destinations (profile, learned-rules, knowledge docs). Don't write directly into the destinations yourself — the Librarian owns the synthesis pass, not you.

## Related

- CLAUDE.md.template Bucket 4 rules 1, 2, 5, 6.
- `pa knowledge --help` — canonical CLI reference.
- `packages/core/roles/librarian/definition.md` — the Librarian role.
- `staging-and-observations.md` — how to stage.