docs: the handbook is the source, the KB is a build artifact - #212
Merged
Conversation
ADR-0038. `sysadmin-self-cultivation` (SSC) is a public handbook whose material is the same material the KB needs — runbooks, platform mechanics, the operating model behind a triage decision. This records which copy is true when the two disagree. **SSC is the single source. The KB is a build artifact, and nothing edits it by hand.** Ingestion runs one way and never back. Two hand-maintained copies drift from the first edit that lands on one side and not the other, and drift here is expensive in a particular way: the KB grounds citations, so a stale chunk produces a confidently cited wrong answer with an audit trail that looks clean. The other direction does not invert. A handbook chapter is prose with an argument in it; a chunk is a retrieval unit. Chunking prose is mechanical; reconstituting an argument from chunks is not. Whichever side is generated has to be the cheaper projection. Second reason, particular to this pairing: SSC is entirely public. Making it the only inbound path means "private material must never reach the KB" is not a rule anyone has to remember — there is no channel for it to arrive through. What follows: - The build script lives here, not in SSC. A handbook that knows the name of its consumer is coupled to it. Interface: `opspilot kb ingest --profile ssc --source <path>`, path as a parameter or env var, never a constant. - Manual runs plus a dry run in CI, no scheduled job. SSC changes a commit or two a week; a cron over that spends nearly all runs doing nothing, which is exactly where a silently broken job and a correctly idle one produce the same empty log. - Conflict detection reports back to SSC. Two handbook modules that contradict each other are a bug in the handbook, not a downstream KB condition — the Conflict/Resolution machinery from ADR-0029 and ADR-0037 is for genuinely competing sources, not one source disagreeing with itself. Write a file for a human; do not open issues automatically. Cost accepted: anything the KB wants that has no readable home in the handbook must either earn a place in SSC's prose or not exist. That is the point — it keeps KB contents traceable to something a person has read and stands behind. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
vicenteliu
force-pushed
the
docs/adr-0038-handbook-is-the-source
branch
from
August 22, 2026 05:02
ecf68a1 to
a2fd62f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ADR-0038.
sysadmin-self-cultivation(SSC) is a public handbook whose material is the same material the KB needs — runbooks, platform mechanics, the operating model behind a triage decision. This records which copy is true when the two disagree.SSC is the single source. The KB is a build artifact, and nothing edits it by hand. Ingestion runs one way and never back.
Why not both, and why not the other way
Two hand-maintained copies drift from the first edit that lands on one side and not the other. Drift here is expensive in a particular way: the KB grounds citations, so a stale chunk produces a confidently cited wrong answer with an audit trail that looks clean.
The reverse direction does not invert. A handbook chapter is prose with an argument in it; a chunk is a retrieval unit. Chunking prose is mechanical; reconstituting an argument from chunks is not — so whichever side is generated has to be the cheaper projection.
Second reason, particular to this pairing: SSC is entirely public. Making it the only inbound path means "private material must never reach the KB" is not a rule anyone has to remember — there is no channel for it to arrive through.
What follows
opspilot kb ingest --profile ssc --source <path>, path as a parameter or env var, never a constant.Cost accepted
Anything the KB wants that has no readable home in the handbook must either earn a place in SSC's prose or not exist. That is the point — it keeps KB contents traceable to something a person has read and stands behind.
Docs only; no code paths touched.
🤖 Generated with Claude Code