docs: collect the silent-failure rules into one section - #144
Merged
Conversation
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, each a sentence or two among material that does announce itself. 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 moves 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. Text is moved rather than rewritten wherever it survives, so 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 now findable. Nothing was dropped. Of 191 backticked spans in the previous file, 190 still appear in CLAUDE.md or a skill; the one casualty is the spelling `/api/v1/me/...`, normalised to `/api/v1/me/*`, which the file already used everywhere else. All 15 figures survive. No code span crosses a newline, which two of them did before this pass. Refs: #140 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U6jNuzK5PZrhDWBxB3t2gY
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
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.
CLAUDE.mdstates its own job in its second paragraph: the map, plus the rules whoseviolation is silent. The second kind was scattered across
Architecture Overview,Key Patterns,HTTP surface,Database,DeploymentandError Handling— a sentence ortwo at a time, mixed in with material that announces itself perfectly well. Someone wanting
to know what fails quietly had to read the whole file and judge every paragraph.
They now sit under one
## Tripwiresheading, grouped by the skill that carries theirreasoning:
daily, the shared-URL batching.Transaction/ReadOnlyTransactionsplit, tiering,weather_forecast_daysversus the 48 h sweep, the two columns that look droppable, the cascade, the schema gate.
initData, 404-never-403, and the threeassertions a controller error test owes.
Everything that does report itself moved to
## Architecture(the binary map, the layertable, routes, the health endpoints, the SQLite engine line) or
## Configuration(env vars,deployment layout).
This is the shape #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, having branched before the outlook work.
Nothing dropped
Text is moved rather than rewritten wherever it survives, so most of the diff reads as
relocation.
The single casualty, named rather than waved off: the spelling
`/api/v1/me/...`,normalised to
`/api/v1/me/*`— the form the file already used in the other four placesit appears.
Also fixed on the way through: two code spans (
`make init`,`make deploy-configs`)were broken across a newline by the previous pass's rewrapping. A check that no span crosses a
newline now returns zero.
17823 → 17234. The saving is incidental — the file was already 2177 under budget, and the
point of this change is that the tripwires are findable, not that they are shorter.
scripts/lint-checks.shclean. Docs only.Refs #140