Note [CRF-8] Structural alternative: a Description() method beside DisplayName() would remove the syntax-tree coupling and the internal-note leak in one move. (Pariston, Ryosuke)

Reusing the trailing comment is what forces the maintainer-note problem in CRF-3 and the doc-comment leak in CRF-7. DisplayName() already proves the codebase carries per-experiment strings as run-time-reachable code. A parallel Description() method would let the author write prose aimed at readers, keep the data reachable without parsing the syntax tree, be unit-testable directly, and give feature-stages.md one obvious thing to link. The author's scope note argues against a new product-side registry, but a method beside DisplayName() is not a registry; it is the pattern already in the file. Both approaches work; this one is worth weighing before this generator becomes the template for the other DOCS reference pages.

🤖

Considered. A Description() API would remove AST coupling, but changes codersdk product metadata and needs owner agreement. Filed DOCS-907 to evaluate it; current hardening remains AST-scoped.

Accepted as a ticketed deferral (DOCS-907). Agreed the Description() direction changes codersdk product metadata and needs owner agreement; keeping the current hardening AST-scoped is reasonable.

🤖

Nit [CRF-21] readDisplayNames returns a presence map whose value is always true, so its name and its render parameter mismodel what the value is. (Mafuuu, Gon, Leorio, Zoro, Knov)

The function returns map[string]bool keyed by experiment value, true when the constant has an explicit case in DisplayName; it carries no display-name strings. The real name comes from exp.DisplayName() at render, which uses this map only as a presence check (if !displayNames[key]). A reader meeting it beside descriptions map[string]string in the render signature reasonably expects displayNames[key] to yield the name and instead gets a bool. This is the same class as the CRF-12 rename (commentText -> commentSentence) the author just fixed one function over. Rename to experimentsWithDisplayName / explicitDisplayNames, use map[string]struct{} since the bool value is never false, and add the one-line doc its sibling readDescriptions already carries.

🤖

Note [CRF-16] readDisplayNames re-parses the same source file and re-walks its Experiment ValueSpecs, duplicating the constant extraction readDescriptions already does. (Netero)

Both functions call parser.ParseFile on *source and iterate ast.Preorder to map Experiment constants (readDescriptions builds value->comment, readDisplayNames builds name->value). The extraction predicate is repeated. Consequence is low: the generator runs once at make gen and a divergent constant form fails loudly rather than emitting wrong output. Parsing once and passing the *ast.File to both extractors would remove the duplicated walk; the clean removal is the DOCS-907 structural change, so this is noted for maintenance, not blocking.

🤖

P3 [CRF-20] The page's completeness rests on the hand-maintained ExperimentsKnown list, which the generator parses enough to verify but never does. (Meruem, raised as Note; orchestrator P3)

The page promises every experiment a deployment can enable, and render derives that set from known (codersdk.ExperimentsKnown), whose only completeness guarantee is the comment "ExperimentsKnown should include all experiments defined above." No test or lint enforces it. Failure mode: a developer adds an Experiment constant with a DisplayName case and a comment but forgets to append it to ExperimentsKnown. Generation still succeeds (it only iterates known), so the page silently omits the experiment. I verified this is reachable, not merely cosmetic: in coderd/coderd.go ReadExperiments logs "ignoring unknown experiment" for a name not in ExperimentsKnown but then appends it unconditionally, so the omitted experiment is still user-enableable via --experiments=<key>. That is exactly the drift this generator advertises it prevents. Rated P3 rather than Note because it defeats the headline "cannot drift" guarantee for a reachable surface; latent only because the current tree has no such gap. Nearly-free fix: readDisplayNames already builds the full set of declared Experiment values; return it (or a sibling) and have render fail when a declared constant is absent from known, so completeness falls out of the parse instead of resting on a comment. (Distinct from CRF-8/CRF-16, which are about how metadata is sourced.)

🤖

P3 [CRF-19] The display-name gate checks that an explicit case exists, not that it returns an authored non-empty name, so it is narrower than the description gate it mirrors. (Knov P3, Hisoka Note)

Two residual gaps on the CRF-1 fix:

1. Empty return. The description gate fails on desc == "" (line 220), but the display-name gate only checks !displayNames[key] (line 224). The rendered value comes from exp.DisplayName(), which nothing checks. A future case ExperimentX: return "" satisfies displayNames["x"] == true, so render proceeds and ships a blank leading cell silently, the same class of silent bad metadata CRF-1 set out to prevent. The fix mirrors the description gate: if !displayNames[key] || displayName == "".

2. Over-broad match. readDisplayNames walks the entire DisplayName FuncDecl body and marks a constant satisfied if it appears in any CaseClause.List. Today DisplayName is one flat switch, so intent and check coincide. If it ever grows a second switch, a guard clause, or a nested switch that mentions an experiment constant for any reason, that constant is marked "has a display name" and render stops failing for it, re-opening the CRF-1 regression. Scoping collection to the SwitchStmt whose tag is the receiver ident would make the check mean what it reads. Both are latent; the empty-return case would at least surface in the docs diff, the scope case would not.

🤖

Note [CRF-15] The table is sorted by experiment key, so the leading "Experiment" (display name) column is not alphabetical. (Chopper)

Rows are ordered by slices.Sort(known) on the key string, so a reader scanning the first column (e.g. "SMTP and Webhook Notifications" under the notifications key) will not find the display names in order. Sorting by key is deterministic and defensible; at 13 rows the cost is small. Worth knowing, not worth changing.

🤖

Declined. Key order is the stable operator-facing identifier order and matches the page's command input; at 13 rows, a separate display-name sort does not improve lookup enough to outweigh that consistency.

Defense accepted; closing. The panel judged 10/10 that sorting by key keeps the Key column (what an operator types into --experiments) alphabetical, and the unsorted display-name column is bounded friction at 13 rows. No re-raise.

🤖