docs(claude): move architecture depth into skills - #140
Conversation
CLAUDE.md drops from 21133 to 11996 bytes, under the 12k budget its own routing block sets. Nothing was removed outright; every subject moved to the skill that already owned its area. beacon-collection gains the source kind vocabulary (BID/ASK/LAST) and the options JSON column, the unconditional Telegram Bot API proxy bypass with the note that the standard HTTPS_PROXY/HTTP_PROXY/NO_PROXY variables are read by nothing here, and cmd/doctor as the operator-only umbrella for rule generation and source auditing. beacon-storage gains the connection PRAGMAs and the two places they are applied from, the BEGIN IMMEDIATE write / deferred read split and why it is what makes busy_timeout reachable, the repository pattern and its transaction helpers, the foreign keys that cascade a source deletion into its history, and the deploy-time schema reconciliation note. beacon-http-api gains the initData HMAC scheme, which previously pointed back at CLAUDE.md and would have dangled, the --api-dsn public-origin flag, and the PublicError contract with the three assertions every controller error test owes. Each skill description was extended alongside its body so the new material has load triggers; content behind a description that does not name it never loads. The working agreement collapses to the pipeline:working-agreement delta form, keeping the branching override in full: branch off alpha, PR against alpha, main only tracks the latest non-prerelease tag, a merge into alpha does not close its issue because GitHub honours the closing keyword only on the default branch, and gh pr create needs an explicit --base alpha. The gate records that make lint runs golangci-lint and scripts/lint-checks.sh, so a green golangci-lint alone is not a green make lint, and that on the pi5 make test dies compiling modernc.org/sqlite under -race and reruns as go test -race -p 1. Env var rows were dropped in favour of internal/env.go, which declares every name, format and consumer; the deployment paragraph defers to deploy/README.md, keeping only the tripwires it does not carry. Two derivable sub-package enumerations were cut from the layer table. Verified by extracting all 227 backticked tokens from the old file: 225 appear verbatim in the new CLAUDE.md, a beacon skill, pipeline:working-agreement, stack-go, or a repo file. The other two survive by meaning rather than spelling. Refs: R21
The Claude Code skill listing truncates a description somewhere above roughly 935 characters, silently dropping the trailing "Load before" triggers that make a description work as a load trigger at all. Rewrite the three oversized descriptions to under 900 characters, keeping the concrete triggers (directories, symbols, env vars) and cutting narrative that the skill bodies already carry: - beacon-collection: 1429 -> 885 - beacon-storage: 1397 -> 809 - beacon-http-api: 1154 -> 825 Every trigger removed from a description still appears in that skill's body, so nothing is lost from the skill as a whole. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzxZmgGZkK5nbM2L2DiQrr
The standard lens set now includes lens O (owner standards); naming a count here would have to be corrected in sixteen files each time it changes, so the delta defers to pipeline:working-agreement instead.
#140 was opened this morning against 16ae37c and slims CLAUDE.md by moving depth into the three project skills. It conflicts now, and much of what it moved has since arrived by other routes — the outlook work carried its own skill sections, and #141 relocated the SQLite PRAGMA and write-lock depth. What did not arrive is canon written nowhere else, so it is taken here verbatim rather than paraphrased. beacon-collection gains the source kind and options JSON column, the cmd/doctor operator umbrella, and the reason the Telegram bot bypasses the proxy in code rather than by configuration: it is the channel that reports collection failures, so it must not share a failure mode with what it reports on. beacon-http-api gains the HMAC key/message order, which is the way round that is easy to invert; the --api-dsn rationale; and the PublicError contract with the three assertions a controller error test owes. beacon-storage gains the repository pattern, the source-deletion cascade and deploy-time schema reconciliation. All four descriptions are replaced by #140's, whose load triggers are strictly wider — a skill that does not load is knowledge that is lost. CLAUDE.md is thinned only where that depth moved, and every tripwire stays: the inner-mux bypass, the batching, the cascade warning and the three-assertion rule keep their sentence. 19330 to 17823. #140's own restructuring of CLAUDE.md into Architecture / Tripwires / Configuration is not taken. It is a larger editorial change than this, the file is already under budget, and it should be its own decision rather than a side effect of salvage. Nothing was dropped: all 210 backticked spans and 15 figures in the previous CLAUDE.md still appear in it or in a skill. Refs: #140 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U6jNuzK5PZrhDWBxB3t2gY
|
Closing as salvaged rather than merged. First, the honest part: this branch merged clean against What carried over
What did not, and whyThe restructuring of Also skipped: the passages this branch moves that had already been written by the outlook work The branch |
CLAUDE.md exists for two things — the map, and the rules whose violation is silent — but the second kind was scattered through Architecture Overview, Key Patterns, HTTP surface, Database, Deployment and Error Handling, a sentence or two at a time among material that announces itself perfectly well. A reader wanting to know what fails quietly had to read the whole file and judge every paragraph. They now sit under one Tripwires heading, grouped by the skill that carries their reasoning: collection, storage, HTTP, startup ordering, release. Everything that does report itself moved to Architecture or Configuration. This is the shape PR #140 proposed; its own version could not be rebased through the day's merges, so the structure is re-derived here over current content, which #140's was missing entirely. Text is moved rather than rewritten wherever it survives, so most of the diff reads as relocation. 17823 to 17234 — the saving is incidental, the file was already under budget, and the point is that the tripwires are findable. Nothing was dropped. Of 191 backticked spans, 190 still appear in CLAUDE.md or a skill; the one casualty is the spelling /api/v1/me/..., normalised to /api/v1/me/*, the form used in the other four places it appears. All 15 figures survive. Also fixed: two code spans that the previous compression pass broke across a newline. A check that no span crosses one now returns zero. Refs: #140 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U6jNuzK5PZrhDWBxB3t2gY
Slims
CLAUDE.mdfrom 21133 to 11996 bytes (-43%), under the 12k budget its own routing block sets. No new skill was created — every block found a home in one of the five that already existed.What moved where
kind(BID/ASK/LAST), theoptionsJSON column,cmd/doctorrulegen/audit, the Telegram proxy bypass and the deadHTTPS_PROXY/HTTP_PROXY/NO_PROXYvariablesbeacon-collectionBEGIN IMMEDIATE/ deferred-read split and theSQLITE_BUSYstory, the repository pattern, foreign-key cascade andRemoveRateSource, deploy-time schema reconciliationbeacon-storageinitDataHMAC scheme,--api-dsn, thePublicErrorcontract and the three controller-error-test assertionsbeacon-http-apiplans/layout, the four agents)pipeline:working-agreement, via its delta forminternal/env.go, which already declares every name, format and consumerdeploy/README.mdEach extended skill also got an extended
description, so the new material has load triggers. A skill that gains content but not triggers loses it.The
beacon-http-apiauth section previously read "The HMAC algorithm is in CLAUDE.md's Key Patterns" — that pointer would have dangled after this change, so the algorithm is now written out in the skill itself.What stays in
CLAUDE.mdThe binary and layer map, the skills table, the routing block,
## Data & Privacy,## Constraints, the gate, startup ordering, and a## Tripwiressection collecting every rule whose violation is silent — tiered reads, theweather_forecast_days48 h sweep, the inner-mux auth mount, 404-not-403,r_*tags going straight to production.Gate notes recorded
make lintandmake lint-neweach run two steps,golangci-lint runandscripts/lint-checks.sh— a greengolangci-lintalone is not a greenmake lint. And on the pi5make testdies compilingmodernc.org/sqliteunder-race; the rerun isgo test -race -p 1.Verification
All 227 backticked tokens were extracted from the old file. 225 appear verbatim in the new
CLAUDE.md, one of the five beacon skills,pipeline:working-agreement,stack-go, or a repo file. The remaining two survive by meaning:/api/v1/me/...— kept as/api/v1/me/*, the same referent in the notation used everywhere else./opt/beacon/artifacts/<VERSION_ID>/— indeploy/README.md(layout tree plus theVERSION_IDdefinition) and literally in.github/workflows/release.yml.Docs only; no code touched, so the gate is unaffected.