docs: update cascade-attention prose from "benchmark missing" to "measured and rejected"
- Dominant language
- Rust
- Stars
- 467
- Forks
- 54
- Avg merge
- 4h 25m
- Merged PRs (30d)
- 310
Description
## Summary
Three passages still frame the cascade-attention default as "off until a benchmark exists", but the benchmark exists and concluded the path is slower in every measured configuration. The framing should change from "not yet measured" to "measured and rejected", linking the report. The constant itself stays `false`.
## Background
One doc passage and two source comments say cascade decode stays default-off until a benchmark record lands under `docs/benchmark_results/`. That record now exists: the M1 Ultra run from 2026-08-03 concludes "cascade decode is slower than the flat #898 launch in every configuration measured, so it ships available but unwired". The prose is stale relative to its own committed evidence.
## Proposed Solution
Rewrite the three short passages to reflect the measured outcome and link or name the existing report. This is reading-comprehension only; `DEFAULT_CASCADE_ENABLED` is unchanged.
## Implementation Notes
- `docs/cascade-attention.md:120` still says "Until such a file exists, the default in `paged_v2::cascade::DEFAULT_CASCADE_ENABLED` stays `false`."
- The report is `docs/benchmark_results/cascade-attention-m1ultra-2026-08-03.md`, which states the measured outcome.
- The same stale framing appears in `src/lib/mlxcel-core/src/paged_v2/cascade.rs:66-67` ("default off ... until `docs/benchmark_results/` carries a number for it") and `:84-86` ("Flip this one constant once a shared-prefix benchmark exists").
## Acceptance Criteria
- [ ] No passage claims the benchmark is missing; each links or names the 2026-08-03 M1 Ultra report
- [ ] `DEFAULT_CASCADE_ENABLED` is unchanged
---
## Original Suggestion
### Title: docs: cascade-attention prose still says the benchmark is missing after it landed
Three passages still frame the cascade-attention default as "off until a benchmark exists" — but the benchmark exists, and it concluded the path is slower in every measured configuration. The framing should change from "not yet measured" to "measured and rejected", linking the report.
## Evidence
- `docs/cascade-attention.md:120` — "Record results under `docs/benchmark_results/cascade-attention--.md` … Until such a file exists, the default in `paged_v2::cascade::DEFAULT_CASCADE_ENABLED` stays `false`."
- `docs/benchmark_results/cascade-attention-m1ultra-2026-08-03.md:1-9` — is that file, concluding "cascade decode is slower than the flat #898 launch in every configuration measured, so it ships available but unwired"
- Same stale framing in `src/lib/mlxcel-core/src/paged_v2/cascade.rs:66-67` ("default off … until `docs/benchmark_results/` carries a number for it") and `:84-86` ("Flip this one constant once a shared-prefix benchmark exists")
## Suggested fix
Rewrite the three short passages (one doc, two source comments) to reflect the measured outcome and link the existing report. Reading comprehension only; the constant itself stays `false`.
## Acceptance criteria
- [ ] No passage claims the benchmark is missing; each links or names the 2026-08-03 M1 Ultra report
- [ ] `DEFAULT_CASCADE_ENABLED` is unchanged
Contributor guide
Research direction
Read the three stale passages in docs/cascade-attention.md:120 and src/lib/mlxcel-core/src/paged_v2/cascade.rs:66-67,84-86, then compare them with docs/benchmark_results/cascade-attention-m1ultra-2026-08-03.md. Update the wording to name or link the measured outcome, ensure no passage says the benchmark is missing, and verify DEFAULT_CASCADE_ENABLED remains false.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100