Skip to content

docs: fix the instructions that actively mislead their reader - #547

Open
Destynova2 wants to merge 1 commit into
mainfrom
docs/fix-misleading-instructions
Open

docs: fix the instructions that actively mislead their reader#547
Destynova2 wants to merge 1 commit into
mainfrom
docs/fix-misleading-instructions

Conversation

@Destynova2

Copy link
Copy Markdown
Contributor

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

File Said Reality
AGENTS.md, CONTRIBUTING.md (x2), docs/how-to/contribute.md gh pr merge --auto --merge The repo disables merge commits. The command is rejected every time. I hit this myself earlier today.
llms.txt 5 links Two files deleted earlier today, one path that never existed, plus the four phantom presets and "7+ core traits" against a traits.rs that now holds two.
AGENTS.md "Disable features at compile time for smaller binaries" Measured: 18.1 MB full, 16.6 MB without dlp/watch/etc. The flags gate the wiring in server/init.rs, not the code. Worth 8%, not a size lever.
docs/slices/MANIFEST.md Hand-maintained LOC counts media listed 1.8k while holding 5.6k; routing 3.9k against 6.3k; shared 1.1k against 2.2k.
CONTRACTS.md [`DEFAULT_TENANT`](crate::storage::DEFAULT_TENANT) A rustdoc intra-doc link inside a Markdown file. Can never resolve.

The manifest counts are now generated: scripts/sync-slice-manifest.sh, with --check for CI. A number that is wrong is worth less than no number.

Missing information that forced guessing

  • AGENTS.md vs CLAUDE.md had 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.
  • The crates.io namesake warning lived only in CLAUDE.md, though AGENTS.md is what an agent reads first. crates.io/crates/grob is an unrelated Windows buffer library. Duplicated where it prevents the mistake.
  • Nothing said where tests go, while three conventions coexist (inline #[cfg(test)], sibling tests.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 marks tests/unit/ as legacy.
  • Nothing documented how to add a provider. src/providers/README.md now traces it, and leads with the answer that matters: most backends need no code at all, just provider_type = "openai" and a base_url. When code is needed, the deepseek shape costs ~8 files and the gemini shape ~28, and the README says which is which.

Checked and deliberately left alone

  • The 24 module READMEs. Both auditors independently called them the healthiest artifact in the repo. Accurate after the trait removal, with a consistent Purpose / Owns / Non-goals / Depends-on shape. Touching them would be churn.
  • CONTRACTS.md. Referenced from CONTRIBUTING.md, intentional, and still true after the trait removal (it never named the deleted traits).
  • Feature-flag gating. An auditor claimed dlp and tap are advertised but unenforced because features/mod.rs declares 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.md resolves; sync-slice-manifest.sh --check passes; shellcheck clean on the new script.

@Destynova2
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
Destynova2 force-pushed the docs/fix-misleading-instructions branch from c1b8b60 to 4e30139 Compare August 6, 2026 17:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant