mikkeli/handbooks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add frontmatter convention (title, collections) to handbooks

Browse Source 
Each handbook now opens with a flat YAML frontmatter block so the
two ingest-time values that actually describe the document -
title and collections - live with it instead of being retyped by
hand at admission time. That drift was real, not hypothetical:
the ingest recipe documented `--collection dev-practice` while the
actual admission used `handbooks`.

`version` deliberately stays out of frontmatter - a file can't
contain the hash of the commit that writes it - and remains a
value the ingest recipe computes fresh, now scoped per-file
(git log -1 -- <file>) rather than the whole repo's HEAD.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EBCcjJvEvhpToahqdsLLA
This commit is contained in:
Mikkeli Matlock
2026-08-22 17:05:23 +09:00
parent 4ed06c7e4b
commit 57e03af2b9
3 changed files with 61 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+51 -14
View File
@@ -28,28 +28,65 @@ a retrieval store, not in a skill.
One markdown file per topic at the repo root. Each file should stand as a single admittable
document — the same shape a human vouches for at KB admission time.
## Ingesting a handbook
Each file opens with a small flat YAML frontmatter block — `title` and `collections` only, no nested
structure, so it stays greppable without a YAML dependency (same reasoning `index.py` itself gives
for hand-parsing `corpora.yaml`):
Markdown needs no conversion and no extraction verifier — admit it straight from this repo:
```bash
index.py admit ~/dev/handbooks/git-operations.md --corpus engineering \
--vouch mikkeli --title 'Git operations' --collection dev-practice \
--version "$(git -C ~/dev/handbooks rev-parse --short HEAD)"
```yaml
---
title: Git operations
collections: [handbooks, dev-practice]
---
```
Without `--title` the document is titled by its filename, which is what a retrieval hit then shows.
`--collection` is a flat cluster tag; getting it wrong costs recall and nothing else.
`title` and `collections` are the two ingest-time values that are actually about the document, so
they live with it instead of being retyped by hand at admission time — that's what let `--collection
dev-practice` and an actual admission of `handbooks` drift apart on 2026-08-22, silently, until it was
noticed by inspection rather than by anything catching it.
⚠ **`--version` is this repo's commit, and it is the one that matters.** Re-admitting replaces a
document outright with no version history, so the pin is the only record of which revision a chunk
reflects.
`version` is deliberately **not** a frontmatter field — a file can't contain the hash of the commit
that writes it, the same self-reference problem any `__COMMIT__` build stamp runs into. It stays a
value computed at admission time, same as before, just scoped to the file rather than the whole repo.
⚠ **Editing a file here does not update the corpus.** Re-admission is deliberate, because the vouch
is a claim about a specific version of a document.
## Ingesting a handbook
Markdown needs no conversion and no extraction verifier — admit it straight from this repo, reading
`title`/`collections` from the frontmatter instead of retyping them:
```bash
F=~/dev/handbooks/git-operations.md
TITLE=$(sed -n '/^---$/,/^---$/{/^title:/s/^title:[[:space:]]*//p}' "$F")
COLLECTIONS=$(sed -n '/^---$/,/^---$/{/^collections:/s/^collections:[[:space:]]*//p}' "$F" \
| tr -d '[]' | tr ',' '\n' | sed 's/^ *//;s/ *$//')
VERSION=$(git -C ~/dev/handbooks log -1 --format=%h -- "$F")
index.py admit "$F" --corpus engineering --vouch mikkeli \
--title "$TITLE" --version "$VERSION" \
$(for c in $COLLECTIONS; do printf -- '--collection %s ' "$c"; done)
```
⚠ **`--version` is the last commit that touched *this file*, not the repo's `HEAD`.** A whole-repo
`HEAD` pin would bump every handbook's recorded version on any unrelated edit, even one that never
touched this document — the per-file form is what actually answers "which revision does this chunk
reflect."
⚠ **Re-admitting replaces a document outright, with no version history kept.** The `--version` pin is
the only record of which revision a chunk reflects, which is also why editing a file here does not by
itself update the corpus — re-admission is deliberate, a fresh claim about a specific version of a
document, not something that should happen automatically on every commit.
## Status
Started 2026-08-21. First handbook, `git-operations.md`, composed 2026-08-21 – 2026-08-22: branching,
committing, merging vs. rebasing, reverting and undoing, remotes and collaboration, tags and releases.
Confirmed ingestible 2026-08-22 — 30 chunks, heading paths intact, retrieved correctly.
Second handbook, `failure-handling.md`, composed 2026-08-22: input contract discipline, failure-
propagation discipline. Environment/verification parity was scoped out of it deliberately — a
different axis (how confidence is established, not how code behaves), queued as a handbook of its
own rather than folded in.
Frontmatter (`title`, `collections`) added to both 2026-08-22, after `--collection dev-practice` in
this file's own recipe was found to have drifted from `handbooks`, the value actually used at
admission — the two ingest-time values that describe the document now live with it instead of being
retyped by hand.