decode-concept-page

[AndreasAbdi]

{
"project": "Model Atlas — Decode Canonical Concept Page",
"branchName": "decode-concept-page",
"description": "Publish one canonical English decode concept page, backed by the existing concept.decode registry record and localized messages, so readers can understand the repeated next-token stage, distinguish it from prefill and sampling, and navigate cleanly through adjacent serving and generation docs.",
"context": {
"customerAsk": "Customer ask alignment: keep the refill batch customer-visible and page-local while strengthening the inference-serving and GPT reader journey with a concept page that already has a registry record but no canonical docs page on current main. Add the canonical English concept page for decode using the existing published concept.decode registry record. Scope: create the canonical concept page plus colocated messages/en.json and any needed assets.json; classify it correctly with the project docs; wire aliases, tags, and related links so readers can move between prefill, prefill-decode-split, kv-cache, autoregressive-generation, sampling-overview, batching, continuous-batching, memory, and speculative-decoding; and add only the focused validation needed for the touched page and discovery surfaces. The page should explain what the decode stage is in plain language, why it repeats token by token, why its performance profile differs from prefill, and how readers should separate decode mechanics from higher-level sampling choices. Keep the slice English-only and avoid reopening locale infrastructure, serving runtime code, or unrelated graph-family churn. Acceptance criteria: the decode concept page exists on current main as a canonical docs page, resolves against the existing registry record, supports serving-path discovery, and focused touched checks pass.",
"problem": "The site already has the published concept.decode registry record and nearby pages covering prefill, prefill-decode-split, kv-cache, autoregressive-generation, sampling-overview, and several serving-system topics, but it still lacks the canonical broad explainer that teaches decode itself as the repeated next-token stage of generation. Readers therefore have to infer decode from narrower cache, batching, or sampling pages instead of landing on one plain-language concept surface that explains why decode repeats, why inter-token latency feels different from prefill latency, and why decode mechanics are not the same thing as token-selection policy.",
"solution": "Publish a canonical English /docs/concepts/decode page using the standard concept-page contract, bind it to the existing concept.decode registry record, make the concept route the clear canonical broad explainer instead of leaving glossary-only discovery as the main surface, connect the required aliases, tags, and related-doc paths to nearby serving and generation pages, and add only the focused validation needed to prove route, message, registry, and discovery integrity for this narrow slice."
},
"acceptanceCriteria": [
"A published canonical docs page exists for decode under the concepts docs tree, with matching English messages and any required local assets.",
"Discovery surfaces treat the concept route as the canonical broad explainer for decode and do not leave readers with competing glossary-only canonical targets for the same concept.",
"The page resolves cleanly to the existing concept.decode discovery record and preserves accurate registry-backed discovery through aliases, tags, and related-doc relationships.",
"The page opens with one folded openingSummary, explains decode in layperson terms, clearly distinguishes the repeated next-token decode loop from prefill, and explains why decode performance often shows up as inter-token latency and cache-growth pressure.",
"The page clearly separates decode mechanics from higher-level sampling choices and guides readers toward sampling-overview when they want to learn how the next token is chosen.",
"Readers can navigate between decode, prefill, prefill-decode-split, kv-cache, autoregressive-generation, sampling-overview, batching, continuous-batching, memory, and speculative-decoding through shipped nearby discovery surfaces with no broken or misleading links.",
"Focused validation covers the touched page contract plus the registry-backed related-doc, route, or search expectations needed for this slice, without broad unrelated test expansion.",
"Quality gate: make typecheck, make lint, and focused tests pass."
],
"userStories": [
{
"id": "decode-concept-page-001",
"title": "Promote decode to the canonical concept discovery surface",
"description": "As a reader searching for decode, I want the existing concept.decode record and route behavior to lead me to one canonical broad explainer so I do not have to infer the topic only from narrower cache, latency, or batching pages.",
"acceptanceCriteria": [
"The existing concept.decode record remains the canonical backing record and is updated only as needed with aliases, related ids, tags, citations, or other controlled metadata that match a broad concept page.",
"Discovery surfaces expose /docs/concepts/decode as the canonical broad explainer for decode, and any retained glossary surface does not compete as the main canonical destination for the same concept.",
"Registry relationships connect the concept page to shipped nearby docs for prefill, prefill-decode-split, kv-cache, autoregressive-generation, sampling-overview, batching, continuous-batching, memory, and speculative-decoding.",
"Discovery metadata distinguishes the broad decode concept from neighboring serving-system pages and sampling pages without introducing duplicate canonical targets or broad taxonomy churn.",
"Typecheck passes",
"Tests pass"
],
"priority": 1,
"passes": true,
"notes": ""
},
{
"id": "decode-concept-page-002",
"title": "Publish the canonical decode concept page",
"description": "As a technical layperson learning about LLM generation and serving, I want a dedicated decode concept page so I can understand the repeated next-token stage before I dive into batching, memory pressure, or token-selection techniques.",
"acceptanceCriteria": [
"A canonical decode docs page exists with matching frontmatter, messages/en.json, and any required local assets.json.",
"The page opens with one folded openingSummary and explains decode in plain language before narrowing into inference-serving context.",
"The page clearly explains that decode begins after prefill, reuses the current prefix and saved key-value state, computes one next-token step, appends that token, and repeats until generation stops.",
"The page clearly explains why decode repeats token by token instead of rereading the whole prompt as one initial pass.",
"The page clearly explains why decode performance often depends on inter-token latency, cache growth, and memory movement in ways that differ from prefill's prompt-side cost profile.",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 2,
"passes": true,
"notes": ""
},
{
"id": "decode-concept-page-003",
"title": "Route readers between decode, serving stages, and sampling",
"description": "As a reader exploring generation tradeoffs, I want related docs, tags, and search surfaces to guide me into the broad decode explainer and then onward to the right neighboring serving and sampling pages.",
"acceptanceCriteria": [
"Representative queries such as decode, decoding, token-by-token generation, next-token step, and inter-token latency return the canonical concept page as a direct relevant result.",
"The concept page renders registry-backed related docs and tag surfaces that connect it to prefill, prefill-decode-split, kv-cache, autoregressive-generation, sampling-overview, batching, continuous-batching, memory, and speculative-decoding.",
"The rendered content explicitly distinguishes decode mechanics from token-selection methods and points readers to sampling-overview when they want to learn how the next token is chosen.",
"At least one neighboring shipped page or discovery surface presents the new concept page as a navigable destination so readers can reach it without typing the exact slug.",
"Browser-visible rendering shows the title, folded summary, tags, related-doc links, and references without broken links or missing-content placeholders.",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 3,
"passes": true,
"notes": ""
},
{
"id": "decode-concept-page-004",
"title": "Add focused validation for the decode concept-page slice",
"description": "As a maintainer, I want targeted automated proof for the decode concept-page slice so route, message, registry, and discovery regressions are caught without unrelated test expansion.",
"acceptanceCriteria": [
"Validation or tests confirm the /docs/concepts/decode route, concept.decode record, and default English messages resolve together.",
"Coverage asserts at least one page-specific discovery outcome and at least one page-specific related-link expectation for the new concept page.",
"Focused checks stay limited to touched content and discovery integrity rather than inventory snapshots, locale churn, runtime serving code, or unrelated suite expansion.",
"Typecheck passes",
"Tests pass"
],
"priority": 4,
"passes": true,
"notes": ""
}
]
}

[AndreasAbdi]

Completed story decode-concept-page-004. Added a focused canonical-page contract test for /docs/concepts/decode that asserts the route, the concept.decode registry record, and the default English colocated page bundle resolve together via localDocsRoute(...) plus validateColocatedPageBundle(...). Verified locally with make typecheck, make lint, bun run pretest, and the focused decode and serving-path discovery test sweep. PR CI is green.

[AndreasAbdi]

BLOCKING review summary for PR #210 (decode-concept-page)

Quality checks

• gh pr checks 210: PASS. All required checks on head 6a7abe0818d1a2e968b51dd8911a9af167d91885 are terminal and passing.
• make test: PASS locally.
• Browser QA: FAIL on acceptance behavior below. I verified /docs/concepts/decode and /docs/architecture in Playwright against a local webpack dev server because the requested docs/internal/processes/manual-qa.md file is not present in this worktree and next dev via Turbopack fails here due workspace-root inference unrelated to this PR.

Project acceptance criteria

• PASS: A published canonical docs page exists for decode under the concepts docs tree, with matching English messages and any required local assets. The new page bundle exists under src/content/docs/concepts/decode/ with page.mdx, messages/en.json, and assets.json.
• FAIL: Discovery surfaces treat the concept route as the canonical broad explainer for decode and do not leave readers with competing glossary-only canonical targets for the same concept. docs/architecture currently renders two separate Decode entries, one to /docs/concepts/decode and one to /docs/glossary/decode, so this discovery surface still presents competing destinations instead of a single clear canonical broad explainer. The implementation path in src/lib/content/architecture.ts includes both concept and glossary pages for foundations architecture concepts, and the changed test in src/tests/content/architecture-index.test.ts now explicitly locks the duplicate Decode entries in.
• PASS: The page resolves cleanly to the existing concept.decode discovery record and preserves accurate registry-backed discovery through aliases, tags, and related-doc relationships. The registry/page/test wiring covers this.
• PASS: The page opens with one folded openingSummary, explains decode in layperson terms, clearly distinguishes the repeated next-token decode loop from prefill, and explains why decode performance often shows up as inter-token latency and cache-growth pressure. Verified in page content and browser render.
• PASS: The page clearly separates decode mechanics from higher-level sampling choices and guides readers toward sampling-overview when they want to learn how the next token is chosen. Present in copy and links.
• PASS: Readers can navigate between decode, prefill, prefill-decode-split, kv-cache, autoregressive-generation, sampling-overview, batching, continuous-batching, memory, and speculative-decoding through shipped nearby discovery surfaces with no broken or misleading links. The page and focused tests cover these links.
• PASS: Focused validation covers the touched page contract plus the registry-backed related-doc, route, or search expectations needed for this slice, without broad unrelated test expansion. The focused decode test exercises route, registry, render, and search behavior.
• PASS: Quality gate: make typecheck, make lint, and focused tests pass. CI is green and make test passed locally.

Behavioral assertion check

• PASS: every passes:true story includes observable behavioral assertions, not only structural gates.

Standards review

factory/docs/standards/docs-writing-standards.md

• PASS: 1. The page is understandable in isolation.
• PASS: 2. The narrative body avoids page-meta/process prose.
• PASS: 3. The first sections explain what decode is and why it matters in plain language.
• PASS: 4. The title and first narrative mention use the full term before shorthand.
• PASS: 5. Sections have distinct jobs.
• PASS: 6. This page is not math-heavy enough to require equations.
• PASS: 7. A graph is not strictly required for this page’s current scope.
• PASS: 8. No math-definition misuse.
• PASS: 9. No reader-shortcut or internal workflow copy.
• PASS: 10. References are present via the registry citation list.
• PASS: 11. Related docs/tags support discovery without carrying the explanation.
• PASS: 12. The copy is concise and direct.

factory/docs/standards/general-website-standards.md

• PASS: 1. Architecture and state fit existing content/registry patterns.
• PASS: 2. Components and interaction reuse existing docs-page components.
• PASS: 3. Styling/visual consistency stays within the established docs shell.
• PASS: 4. Accessibility appears intact on the rendered page.
• PASS: 5. Responsive behavior was not obviously regressed by the added page.
• PASS: 6. Performance/resilience risk is low for this static content slice.
• FAIL: 7. Browser/manual verification surfaced a real discovery regression: the architecture index still exposes competing Decode destinations instead of one canonical broad explainer.
• PASS: 8. Localization scope is explicit and English-only as requested.
• PASS: 9. Test evidence is focused and behavior-oriented.

Review rules application

• FAIL correctness before style: the canonicalization requirement is not fully met because a shipped discovery surface still shows both Decode routes as parallel options.
• PASS solution fit: the new concept page itself is correctly written and wired.
• PASS architecture/dependency fit: the slice stays within docs/registry/search boundaries.
• PASS readability/maintainability: the page and focused test are straightforward.
• PASS tests/evidence: automated coverage is appropriate.

Required fix

• BLOCKING: canonicalize architecture/discovery listings so decode does not appear as competing concept and glossary entries on the same shipped surface. At minimum, docs/architecture should prefer the concept route as the sole broad-explainer destination for concept.decode, and the tests that currently assert both entries should be updated accordingly.

[AndreasAbdi]

Addressed the blocking architecture-surface feedback on head a9460445.

Changes made:

• Canonicalized loadPublishedArchitectureEntries(...) to dedupe pages that share one registryId and prefer the concept route over a glossary sibling.
• Verified this removes the competing /docs/glossary/decode destination from /docs/architecture while keeping /docs/concepts/decode as the sole Decode entry.
• Updated focused architecture browse tests to lock the canonical Decode behavior and align the current canonical Key-value cache route and resulting architecture entry count.

Validation:

• make typecheck
• make lint
• bun run pretest
• bun test src/tests/content/architecture-index.test.ts src/lib/content/glossary-architecture-index.test.ts
• Browser QA on http://localhost:3564/docs/architecture against the local webpack dev server confirmed one visible Decode link to /docs/concepts/decode and no glossary duplicate.

This addresses the blocking review requirement that /docs/architecture prefer the concept route as the sole broad-explainer destination for concept.decode.

[AndreasAbdi]

Addressed the CI mergeability failure on head 84797d8.

What changed:

• Updated src/lib/content/content-reconciliation-browse-index.test.ts so the shared architecture browse convergence test now expects the canonical /docs/concepts/kv-cache destination instead of the stale glossary route.

Why this was needed:

• The product code and slice-specific architecture tests were already canonicalizing shared concept/glossary records correctly, but the broader reconciliation browse suite still encoded the older architecture URL. CI failed in make test on that stale expectation.

Validation:

• make typecheck
• make lint
• WEBSITE_TEST_PARALLEL_WORKERS=1 make test

This is mergeability-only follow-up on the current PR head; no PRD story scope changed.