mikkeli
9aa0916d95
The rebase conflict-marker explanation had HEAD and the incoming
side backwards, verified by reproducing all three merge/rebase
scenarios in a throwaway repo. Rewrote that passage around the
actual behavior instead of a merge-vs-rebase binary, since the old
"merge = HEAD is trunk" claim was also only true for one of the two
merge scenarios the doc itself describes.
Also fixes, from the same review pass:
- push-rejection handling in Branching split into its two real
causes (protection/permission vs. plain non-fast-forward)
- the commit-body trigger reworded to match how it's actually used
("why worth keeping", not just subject length)
- a mislabeled checkout equivalent for unstaging (that was always
git reset's job, not checkout's)
- the vendor-sync example no longer assumes upstream's trunk is
named master
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EBCcjJvEvhpToahqdsLLA
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
(
kb-engineeringfor halogen). - 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.
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.