ffn-pages-from-phase-3

[AndreasAbdi]

{
"project": "Model Atlas — Phase 3 FFN Variant Pages",
"branchName": "ffn-pages-from-phase-3",
"description": "Publish the missing Phase 3 FFN-adjacent pages for standard FFN and common activation or gated FFN variants so readers can move from the existing FFN overview to concrete transformer block choices.",
"context": {
"customerAsk": "Add the missing Phase 3 modules around FFNs, including items like SwiGLU and ReLU.",
"problem": "The site already explains feed-forward networks, mixture of experts, and activations at a broad level, but it still lacks the concrete FFN subtype and activation-variant pages that later model and module docs will reference. Readers cannot yet open canonical pages for standard FFN, ReLU, LeakyReLU, SiLU, or SwiGLU, compare how those choices change FFN behavior, or reliably find those topics through related docs and search.",
"solution": "Publish a focused FFN family cluster covering standard FFN, ReLU, LeakyReLU, SiLU, and SwiGLU using the existing canonical docs patterns, then wire aliases, related docs, and search behavior so readers can navigate from the broad FFN and activation foundations to the correct subtype page."
},
"acceptanceCriteria": [
"Published canonical pages exist for standard-ffn, relu, leaky-relu, silu, and swiglu, each with a matching registry record, route, and English content",
"The standard FFN page explains the dense baseline block and clearly distinguishes it from the broader feed-forward-network overview and from mixture-of-experts",
"The activation pages explain what behavior each variant changes inside an FFN, and the SwiGLU page makes its gated-FFN relationship to SiLU explicit",
"Related-doc and tag navigation lets readers move between feed-forward-network, activation, standard-ffn, relu, leaky-relu, silu, swiglu, and mixture-of-experts without dead ends",
"Representative searches such as standard FFN, ReLU, LeakyReLU, SiLU, and SwiGLU return the canonical page for that term rather than only a broader foundation page",
"Page copy is layperson-readable, uses one folded summary, avoids phase or process language, and keeps math definitions symbol-only when formulas are shown",
"make typecheck, make lint, and make test pass"
],
"userStories": [
{
"id": "ffn-pages-from-phase-3-001",
"title": "Publish the standard FFN page",
"description": "As a reader who already understands what an FFN is in broad terms, I want a dedicated standard-FFN page so I can distinguish the default dense transformer block from MoE and from gated FFN variants.",
"acceptanceCriteria": [
"A canonical page exists at /docs/glossary/standard-ffn with a published registry record and readable route title for Standard FFN",
"The page explains the expand to activate to project dense FFN pattern in plain language and states where it sits relative to attention inside a transformer block",
"The page clearly distinguishes standard FFN from the broader feed-forward-network overview and from mixture-of-experts",
"Related docs link to feed-forward-network, mixture-of-experts, and at least one activation variant page",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 1,
"passes": true,
"notes": ""
},
{
"id": "ffn-pages-from-phase-3-002",
"title": "Publish the ReLU and LeakyReLU pages",
"description": "As a reader comparing common nonlinearities, I want ReLU and LeakyReLU pages so I can understand the simplest FFN activation choices and what changes when negative values are allowed to leak through.",
"acceptanceCriteria": [
"Canonical pages exist for /docs/glossary/relu and /docs/glossary/leaky-relu, each with published registry records and search-friendly aliases",
"The ReLU page explains zeroing negative activations in plain language and ties the concept back to FFN hidden-state transforms",
"The LeakyReLU page explains how a small negative slope changes behavior relative to ReLU without turning into a benchmark or optimization guide",
"Both pages link back to activation, feed-forward-network, and standard-ffn, and they cross-link to each other as nearby variants",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 2,
"passes": true,
"notes": ""
},
{
"id": "ffn-pages-from-phase-3-003",
"title": "Publish the SiLU and SwiGLU pages",
"description": "As a reader looking at modern LLM architectures, I want SiLU and SwiGLU pages so I can understand the smoother activation used in many recent stacks and how SwiGLU turns that idea into a gated FFN variant.",
"acceptanceCriteria": [
"Canonical pages exist for /docs/glossary/silu and /docs/glossary/swiglu, each with published registry records and aliases that cover spaced and capitalized query forms",
"The SiLU page explains the smooth self-gated activation behavior in plain language and links it to FFN hidden transforms",
"The SwiGLU page explains the gated two-branch FFN structure, not just the activation name, and makes the relationship to SiLU explicit",
"SwiGLU is contrasted with standard-ffn and mixture-of-experts so readers understand that it changes the FFN block shape but stays in the same transformer slot",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 3,
"passes": true,
"notes": ""
},
{
"id": "ffn-pages-from-phase-3-004",
"title": "Make the FFN variant family navigable and searchable",
"description": "As a reader exploring transformer components, I want the FFN family pages to be connected through related docs and search so I can move from the broad overview to the right subtype or activation page in one step.",
"acceptanceCriteria": [
"Feed-forward-network, activation, standard-ffn, relu, leaky-relu, silu, swiglu, and mixture-of-experts form a coherent related-doc cluster with no broken or one-way dead-end links inside the shipped family",
"Search surfaces return the canonical page for representative queries standard FFN, ReLU, LeakyReLU, SiLU, and SwiGLU",
"Parent-page copy and related-doc presentation make it clear when a page is a broad foundation page versus a specific subtype or activation variant",
"Browser-visible routes for the new pages render titles, summaries, related-doc links, and tag pills without missing-content placeholders",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 4,
"passes": true,
"notes": ""
}
]
}

[AndreasAbdi]

BLOCKING: GitHub currently reports this PR as mergeable: CONFLICTING with mergeStateStatus: DIRTY, so it cannot be merged as-is. Please rebase onto main, resolve the merge conflicts, and push the updated branch.

Review summary:

• Local quality checks passed: make typecheck, make lint, and make test.
• Live GitHub required checks: none reported on the current head (gh pr checks returned no checks).
• Browser QA: spot-checked the built glossary pages for standard-ffn, relu, and swiglu via Playwright against prerendered HTML fallback. Titles, summaries, sections, related links, and tag pills rendered as expected. The task-referenced docs/temp/processes/manual-qa.md file is not present in this worktree, so I used the available built output instead.
• Behavioral assertion check: all four stories marked passes:true include behavioral assertions beyond structure/compile-only checks.

Acceptance criteria:

• PASS — Published canonical pages exist for standard-ffn, relu, leaky-relu, silu, and swiglu, each with a matching registry record, route, and English content. Verified in the diff across the new glossary bundles and concept registry records.
• PASS — The Standard FFN page explains the dense baseline block and clearly distinguishes it from the broader feed-forward-network overview and from mixture-of-experts. Verified in standard-ffn/messages/en.json and rendered output.
• PASS — The activation pages explain what behavior each variant changes inside an FFN, and the SwiGLU page makes its gated-FFN relationship to SiLU explicit. Verified in the new message files plus search/render tests.
• PASS — Related-doc and tag navigation lets readers move between feed-forward-network, activation, standard-ffn, relu, leaky-relu, silu, swiglu, and mixture-of-experts without dead ends. Verified through registry relatedIds, updated broad foundation pages, and ffn-variant-family-navigation.test.ts.
• PASS — Representative searches such as standard FFN, ReLU, LeakyReLU, SiLU, and SwiGLU return the canonical page for that term rather than only a broader foundation page. Verified by the new search tests using docsSearchApi and pageBaseUrl assertions.
• PASS — Page copy is layperson-readable, uses one folded summary, avoids phase or process language, and keeps math definitions symbol-only when formulas are shown. Verified in the new content and convergence tests; these pages do not introduce math sections.
• PASS — make typecheck, make lint, and make test pass locally.

Blocking issue to fix before merge:

• BLOCKING — Rebase and resolve the merge conflict with main, then push the updated head so the PR can be merged.

[AndreasAbdi]

Addressed the blocking mergeability feedback.

What changed:

• Rebased ffn-pages-from-phase-3 onto the current main and force-pushed the updated PR head at 158981d.
• Merged the newer shared glossary inventory and registry-runtime updates from main back into this branch so the FFN-family pages stay mergeable on the current published docs surface.
• Removed the stale superseded src/lib/content/activation-family-glossary.test.ts coverage in favor of the split FFN-family tests already on this branch, and restored the stable chunked glossary auto-link convergence test from main.
• Kept the FFN-family navigation additions while preserving the newer activation -> quantization related-doc link that landed on main.

Validation:

• make typecheck
• make lint
• make test

This addresses the earlier BLOCKING comment about the PR being mergeable: CONFLICTING / mergeStateStatus: DIRTY.