mikkeli
ccefd1751b
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EvxzSKi1zR395wvYXUenVE
56 lines
2.7 KiB
Markdown
56 lines
2.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.
|
||
|
||
## Ingesting a handbook
|
||
|
||
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)"
|
||
```
|
||
|
||
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.
|
||
|
||
⚠ **`--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.
|
||
|
||
⚠ **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.
|
||
|
||
## 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.
|