mikkeli
57e03af2b9
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
93 lines
4.7 KiB
Markdown
93 lines
4.7 KiB
Markdown
# Handbooks
|
||
|
||
Instance-agnostic reference material for coding agents — the verbose, citable kind that belongs in
|
||
a retrieval store, not in a skill.
|
||
|
||
## What goes here
|
||
|
||
- Public standards, style guides, and conventions that apply regardless of which box or project is
|
||
running — general git operations, language style guides, CERT/MISRA-style rulebooks.
|
||
- Long-form and specific. A handbook can be as detailed as it needs to be; nothing here is loaded
|
||
into a model's context wholesale, so length carries no per-turn tax.
|
||
|
||
## What does not go here
|
||
|
||
- **Anything specific to one machine or one project.** A local Gitea's branch-naming rule, this
|
||
box's PR checklist — that's instance-bound and belongs in that project's own KB corpus instead
|
||
(the `engineering` corpus, for
|
||
[halogen](https://git.novoyuuparosk.org/mikkeli/halogen-workstation-roadmap)).
|
||
- **Short, prescriptive procedures achievable within a context window or two.** That's a skill, not
|
||
a handbook — it gets loaded, not retrieved. See `skills/` in the halogen-workstation-roadmap repo
|
||
for the sibling convention.
|
||
- **The retrieval store itself.** This repo holds the source-of-truth markdown a human has vouched
|
||
for. The chunked, embedded index built from it is derived and rebuildable state — it lives beside
|
||
whichever KB is consuming it, never committed here.
|
||
|
||
## Format
|
||
|
||
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.
|
||
|
||
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`):
|
||
|
||
```yaml
|
||
---
|
||
title: Git operations
|
||
collections: [handbooks, dev-practice]
|
||
---
|
||
```
|
||
|
||
`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 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.
|
||
|
||
## 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.
|