# SOP: Encode Unseen Knowledge Into The Repo

Use this SOP when important context still lives in Google Docs, chat threads,
tickets, or people's heads.

## Goal

Make agent-invisible knowledge discoverable in the codebase so a fresh session
can act on it without relying on prior conversation.

## Trigger Signals

- The agent keeps asking how the system works.
- Humans say "we decided this in Slack" or "follow what X said last week."
- Reviews reference product or security rules that are not written in-repo.
- New sessions repeat discovery work that should already be settled.

## Execution SOP

1. List the invisible knowledge sources: docs, chats, tacit team rules, verbal decisions.
2. For each source, ask: is this architecture, product behavior, security policy,
   reliability expectation, plan context, or reference material?
3. Encode it into the matching repo artifact:
   - architecture -> `ARCHITECTURE.md`
   - product behavior -> `docs/product-specs/`
   - design rationale -> `docs/design-docs/`
   - execution state -> `docs/exec-plans/`
   - repeated external references -> `docs/references/`
   - quality or reliability expectations -> `docs/QUALITY_SCORE.md` or `docs/RELIABILITY.md`
4. Replace vague statements with operationally useful wording.
5. Remove or deprecate stale copies so the repo keeps one discoverable truth.

## Good Encoding Rules

- Write for discoverability, not for literary completeness.
- Prefer short documents with clear filenames.
- Link related artifacts together.
- Store durable rules, not meeting transcripts.
- Update the repo in the same session that the decision is made.

## Definition Of Done

- A fresh agent can discover the relevant rule without asking a human.
- The same fact is not scattered across multiple contradictory files.
- The new artifact lives close to the code or workflow it governs.