Skip to content

[Docs] Correct the four front-door claims the last day of measurement invalidated - #23

Merged
rwkeyes merged 1 commit into
dirigo/0.2.12-verifiedfrom
docs/claims-audit
Nov 15, 2026
Merged

rwkeyes merged 1 commit into
dirigo/0.2.12-verifiedfrom
docs/claims-audit

Conversation

@rwkeyes

@rwkeyes rwkeyes commented Nov 15, 2026

Copy link
Copy Markdown
Owner

Problem and result

The front page and the first-run path were rewritten on 2026-11-13; a day of measurement since then has made four
statements in them false, imprecise, or a trap. All four are on pages a newcomer reads before anything else.

  1. DIRIGO.md listed a limit that no longer exists — "the --conv-route-batch-after threshold was not swept" and
    the switch back was unmeasured. Both were measured on 2026-11-14 (§7): the switch back costs a conversation 1.9 s
    per re-open, so 4 stands, and sweeping it revealed the config key was never read (fixed in b906f0b5).
  2. README.md gave no threshold — "runs of single-shot prompts" reads as "one request flips it". It is four.
  3. The same table quoted −12…−22 % without the client count — that is 1–4 clients; at 8 it is nothing.
  4. Both quick starts named data/expert-profile.bin without saying which model shape it fits. The profile is
    matched on the expert count, not the quantization: 48×512 for the full model, 48×256 for the pruned Coder — and
    the wrong one stops the engine with it is a profile for a different model, which reads like a corrupted pack.

Plus one dead link a reader could actually hit: docs/HOW_IT_WORKS.md pointed at ../README.md#how-does-it-work, a
heading the README rewrite removed.

Related discussion

Approach

Audited the ten front-door pages for links, anchors, and every claim touching batch_after, the cache switch, TTFT
numbers, --expert-profile and PLE; fixed only what was actually wrong.

Validation

Passed:

  • The 512 figure is measured, not assumed: read from the IQ3_XXS GGUF's own metadata (48 layers,
    expert_count = 512), so "IQ2_/IQ3_/Q2_0 → expert-profile.bin" is grounded; the Coder packs' headers are 48×256.
  • Every relative link and anchor in the ten front-door pages resolves after the changes (checker: punctuation
    stripped, spaces → hyphens, explicit <a name> honoured).
  • The README renders: 8 tables, 60 rows, no ragged rows.

Failed:

  • My first "fix" broke a working link. I changed MODELS.md#a-big-graphics-card-and-little-ram to #pick-by-memory
    because my slug function collapsed the double hyphen GitHub produces when a / is removed from
    "History / older measurements". The anchor resolves; the change is reverted, and the checker now uses GitHub's rule
    (each space → one hyphen, no collapsing).

Not run:

  • No change to any number or measurement; nothing re-measured, the pages now agree with the inventory instead.

Limits

  • The audit is limited to the front-door pages listed in the commit; bench/results/ and apps/host/docs/ still carry
    their historical dead links by design (they are evidence, not navigation).

Four fixes to pages a first-time reader meets before anything else.

1. DIRIGO.md said the batch_after threshold "was not swept" and that the
   router's switch back was unmeasured. Both were measured on 2026-11-14:
   the switch back costs a conversation 1.9 s per re-open, so the value
   stays at 4, and sweeping it found that the config key was never read
   (fixed in b906f0b). The page now says that instead of listing a limit
   that no longer exists.

2. README's change table said the cache goes off "for runs of single-shot
   prompts" without the number, so a reader could think one request flips
   it. It says four, and what the other settings cost.

3. The same table claimed the routing is worth -12..-22 % without saying
   at how many clients: it is 1-4, nothing at 8.

4. Both quick starts named data/expert-profile.bin without saying which
   model shape it fits. The profile is matched on the expert count, not
   the quantization: 48x512 for the full model, 48x256 for the pruned
   Coder - and the wrong one stops the engine with "it is a profile for a
   different model", which reads like a corrupted pack. Verified from the
   IQ3_XXS GGUF's own metadata (expert_count 512) before writing it.

Also repairs the one dead link a reader could hit: docs/HOW_IT_WORKS.md
pointed at ../README.md#how-does-it-work, a heading the README rewrite
removed. A second candidate (MODELS.md#a-big-graphics-card-and-little-ram)
was left alone after checking: that anchor resolves, and my first attempt
at "fixing" it would have broken a working link.
@rwkeyes
rwkeyes merged commit ba25110 into dirigo/0.2.12-verified Nov 15, 2026
3 checks passed
@rwkeyes
rwkeyes deleted the docs/claims-audit branch November 15, 2026 12: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