---
name: codebase-knowledge
version: 2.0.0
description: "Cached domain knowledge consumed BEFORE implementing any feature. Reads `.claude/skills/codebase-knowledge/_index.json` (machine-readable, regenerated by `documenter`) for fast filter, then reads only the affected `domains/<slug>.md` files. Avoids re-exploring the codebase every session."
---

# Codebase Knowledge — Domain Knowledge Reader (v2.0.0)

**ALWAYS invoke BEFORE implementing any feature.**

This skill is the **read side** of the project memory layer maintained by the `documenter` and `domain-updater` agents. Its job is to load just enough context for the next change without re-discovering the whole codebase.

## Storage layout (maintained by `documenter` v2.0.0)

```
.claude/skills/codebase-knowledge/
├── SKILL.md                  # this file
├── TEMPLATE.md               # template for new domain files (no version — it is a template)
├── _INDEX.md                 # human-readable list of all domains
├── _index.json               # machine-readable index — SOURCE OF TRUTH for filter
└── domains/
    ├── <slug>.md             # one file per domain. ≤ 8 KB / ~2k tokens / 200 lines
    └── <slug>.archive.md     # commits/wisdom older than the cap (read on demand only)
```

## Read protocol (token-efficient)

| # | Step | Tool |
|---|---|---|
| 1 | **Resolve which domain(s) you need** by glob/grep on the affected file paths against `.claude/config/domain-mapping.json` | Bash + jq |
| 2 | **Read `_index.json` first** — one query gives you `last_commit`, `tags`, `connections` for every domain | `jq '.domains[] \| select(.slug == "auth")' _index.json` |
| 3 | **Read only the matched `domains/<slug>.md`** files — never `cat domains/*.md` (that defeats the budget) | Read |
| 4 | **Follow `connections`** if the change crosses a domain boundary; read those neighbours too | Read |
| 5 | **Skip `<slug>.archive.md`** unless `_index.json` flags `status: archived` and you actually need history | Read |

## Domain file shape

Defined by `documenter` v2.0.0 — see `TEMPLATE.md` in this folder for the canonical layout. Required sections:

- YAML frontmatter (`domain · tags · owner · last_commit · last_date · files_count · connections · status`)
- TL;DR (≤ 3 lines, front-loads boundary)
- Files table (path → role)
- Connections table (bidirectional: → and ← rows)
- Recent Commits (capped at 20)
- Attention Points (capped at 10)
- Problems & Solutions (capped at 5, append-only)

## Workflow

1. **Before coding** — read this skill, then `_index.json`, then the affected `domains/<slug>.md` files.
2. **During coding** — note any new connection, gotcha, or non-obvious decision (you do not write here directly).
3. **After commit** — `documenter` maps files+commits, `domain-updater` records the wisdom you collected.

## Rules

1. **READ `_index.json` FIRST** — it is regenerated each commit; it is the cheapest way to filter.
2. **NEVER `cat domains/*.md`** — you will blow the context budget.
3. **BIDIRECTIONAL CONNECTIONS** — if `auth.md` lists `→ api`, then `api.md` MUST list `← auth`. If you spot a missing reverse edge, surface it for `domain-updater`.
4. **ARCHIVE FILES ARE OPT-IN** — read `<slug>.archive.md` only when `_index.json` shows `status: archived` or when you need pre-cap history.
5. **DO NOT EDIT DOMAIN FILES DIRECTLY** — only `documenter` and `domain-updater` write here. If something is wrong, fix the agent or report drift.
6. **TRUST `last_commit`** — if `_index.json#last_commit` ≠ HEAD, the documenter forgot to run; pause and fix instead of working with stale knowledge.

## See Also

- `documenter` v2.0.0 — writes to this layout (after every commit)
- `domain-updater` v2.0.0 — writes session wisdom (Problems & Solutions, Attention Points)
- `docs-tracker` v2.0.0 — file → domain mapping rules
- `claude-md-compactor` v2.0.0 — keeps `CLAUDE.md` ≤ 20 KB; this layer keeps each domain ≤ 8 KB