docs: fix the instructions that actively mislead their reader - #547
Open
Destynova2 wants to merge 1 commit into
Open
docs: fix the instructions that actively mislead their reader#547Destynova2 wants to merge 1 commit into
Destynova2 wants to merge 1 commit into
Conversation
Destynova2
enabled auto-merge (squash)
August 6, 2026 08:04
Audited every doc against the audience it claims to serve: operator, contributor, and coding agent. An agent cannot ask a follow-up question, so an ambiguous or wrong instruction is a defect, not a nuance. Wrong instructions, in order of harm: - Four files told the reader to run 'gh pr merge --auto --merge'. The repo disables merge commits, so that command is rejected every time. I hit this myself earlier in this session. Now --squash everywhere. - llms.txt had five dead links, including two files deleted earlier today and one path that never existed, plus the four phantom presets and a claim of '7+ core traits' against a traits.rs that now holds two. - AGENTS.md said 'disable features at compile time for smaller binaries'. Measured: 18.1 MB full versus 16.6 MB without dlp/watch/etc. The flags gate the wiring in server/init.rs, not the code. Now stated as what it is. - docs/slices/MANIFEST.md carried hand-maintained LOC counts that had drifted badly: media listed 1.8k while holding 5.6k, routing 3.9k against 6.3k. Regenerated, and scripts/sync-slice-manifest.sh --check keeps them honest. - CONTRACTS.md used a rustdoc intra-doc link inside a Markdown file, where it can never resolve. Missing information that made contributors guess: - AGENTS.md and CLAUDE.md had no stated boundary and had drifted apart. AGENTS.md is now the map (what exists, where), CLAUDE.md the manual (how to write and land code), and AGENTS.md says so and defers on release mechanics. - The crates.io namesake warning lived only in CLAUDE.md, though AGENTS.md is what an agent reads first. Duplicated where it prevents the mistake. - Nothing anywhere said where tests go, while three conventions coexist. CLAUDE.md now documents the rule the codebase already mostly follows. - Nothing documented how to add a provider. src/providers/README.md now traces it, and says first that most backends need no code at all, just provider_type = "openai" and a base_url. 1727 tests pass, markdownlint clean, sync-slice-manifest --check passes.
Destynova2
force-pushed
the
docs/fix-misleading-instructions
branch
from
August 6, 2026 17:21
c1b8b60 to
4e30139
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
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.
Third pass. This one audited every doc against the audience it claims to serve: operator, contributor, coding agent. An agent cannot ask a follow-up question, so a wrong instruction is a defect rather than a nuance.
Instructions that were actively wrong
AGENTS.md,CONTRIBUTING.md(x2),docs/how-to/contribute.mdgh pr merge --auto --mergellms.txttraits.rsthat now holds two.AGENTS.mddlp/watch/etc. The flags gate the wiring inserver/init.rs, not the code. Worth 8%, not a size lever.docs/slices/MANIFEST.mdmedialisted 1.8k while holding 5.6k;routing3.9k against 6.3k;shared1.1k against 2.2k.CONTRACTS.md[`DEFAULT_TENANT`](crate::storage::DEFAULT_TENANT)The manifest counts are now generated:
scripts/sync-slice-manifest.sh, with--checkfor CI. A number that is wrong is worth less than no number.Missing information that forced guessing
AGENTS.mdvsCLAUDE.mdhad no stated boundary and had drifted (AGENTS.md untouched since June 18, CLAUDE.md updated July 26, each holding unique content). They are not duplicates: AGENTS.md is the map (what exists, where), CLAUDE.md the manual (how to write and land code). AGENTS.md now says so and defers to CLAUDE.md on release mechanics instead of carrying a weaker copy.crates.io/crates/grobis an unrelated Windows buffer library. Duplicated where it prevents the mistake.#[cfg(test)], siblingtests.rs,tests/).dlp/uses two of them at once, which is intended but looked like drift. CLAUDE.md now states the rule the codebase already mostly follows, and markstests/unit/as legacy.src/providers/README.mdnow traces it, and leads with the answer that matters: most backends need no code at all, justprovider_type = "openai"and abase_url. When code is needed, thedeepseekshape costs ~8 files and thegeminishape ~28, and the README says which is which.Checked and deliberately left alone
CONTRACTS.md. Referenced fromCONTRIBUTING.md, intentional, and still true after the trait removal (it never named the deleted traits).dlpandtapare advertised but unenforced becausefeatures/mod.rsdeclares them ungated. Verified false: they gate the initialization path, so the behaviour really does disappear. Only the size claim was wrong, and that is now documented rather than "fixed" by ripping out working flags.Verification
1727 tests pass; markdownlint clean; every relative link in
llms.txt,AGENTS.md,CLAUDE.md,CONTRACTS.mdresolves;sync-slice-manifest.sh --checkpasses; shellcheck clean on the new script.