docs: codify feature-acceptance criterion (LLM-author utility)
Adds DESIGN.md "Feature-acceptance criterion" as a top-level section: a feature ships only if (1) an LLM author naturally produces code that uses it, and (2) it measurably improves correctness or removes redundancy. Aesthetic appeal and human ergonomics do not count. Mirrored in CLAUDE.md as "Feature acceptance: LLM utility", paired with the existing "Design rationale != implementation effort". The two together narrow valid feature rationales to one thing: what the LLM author gets out of the feature. Trigger: the typeclass-design conversation around 22a. Rule was implicit in many past decisions (Decision 1's JSON-over-text choice, Decision 10's "what LLMs are good at" reasoning) but never stated as a feature-gate. Codifying it now means future feature proposals get evaluated against an articulated criterion instead of being re-derived each time. Documentation-only; no Rust, schema, or bench changes. Test state 288/0/3 unchanged.
This commit is contained in:
@@ -10782,3 +10782,86 @@ All three bench scripts re-run sequentially after edits:
|
||||
- **Family 21+** — typeclasses, polymorphic ADTs at runtime,
|
||||
pattern-binding generalisation. Orchestrator-level fork; needs
|
||||
direct user input before dispatch.
|
||||
|
||||
## 2026-05-09 — Feature-acceptance criterion codified
|
||||
|
||||
Trigger: the typeclass-design conversation around 22a surfaced a
|
||||
recurring meta-question — when is a proposed feature actually
|
||||
worth shipping. The negative form was already in CLAUDE.md
|
||||
("Design rationale ≠ implementation effort": cost is not a
|
||||
reason for a feature). The positive form was implicit in many
|
||||
decisions (Decision 10's reasoning explicitly invokes "what
|
||||
LLMs are good at vs. not"; the JSON-over-text choice in
|
||||
Decision 1 is justified by LLM-readability) but never stated as
|
||||
a feature-acceptance gate.
|
||||
|
||||
This entry codifies it. New top-level section in DESIGN.md
|
||||
("Feature-acceptance criterion"): a feature ships only if (1)
|
||||
an LLM author naturally produces code that uses it without
|
||||
prompting toward it, AND (2) the feature measurably improves
|
||||
correctness or removes redundancy. Aesthetic appeal — "feels
|
||||
elegant", "is idiomatic" — does not count; neither does human
|
||||
ergonomics. Two corollaries: human-attractive but LLM-neutral
|
||||
features (point-free style, operator overloading, implicit
|
||||
conversions) are cut; human-hostile but LLM-friendly features
|
||||
(JSON authoring surface, mandatory mode annotations, mandatory
|
||||
top-level signatures) are kept.
|
||||
|
||||
Mirrored briefly in CLAUDE.md as a sub-section
|
||||
"Feature acceptance: LLM utility", paired with the existing
|
||||
"Design rationale ≠ implementation effort". The two together
|
||||
fully narrow the space of valid feature rationales: not cost,
|
||||
not aesthetics, only LLM-author utility.
|
||||
|
||||
### Why now
|
||||
|
||||
The typeclass conversation was the surfacing event. When asked
|
||||
to construct two examples that pure monomorphisation cannot
|
||||
handle (heterogeneous Show-able container; higher-rank
|
||||
polymorphism), the natural response was: both are features that
|
||||
an LLM author would not unprompted produce. Heterogeneous
|
||||
containers reduce to closed-world sum types in practice;
|
||||
higher-rank polymorphism reduces to two separate functions.
|
||||
Without the rule explicitly named, the next instance of "should
|
||||
we add feature X" would replay the same reasoning from scratch.
|
||||
Codifying it now means future feature proposals get gated by an
|
||||
articulated criterion, not by re-derivation.
|
||||
|
||||
### Implications for 22a (next iter)
|
||||
|
||||
The rule is the explicit basis for the typeclass-design choices
|
||||
that 22a will make:
|
||||
|
||||
- **Monomorphisation as default dispatch strategy.** A pure-mono
|
||||
language with rank-1-only polymorphism is exactly what a
|
||||
natural LLM author produces. Dictionaries would handle features
|
||||
(heterogeneous containers, higher-rank) that are real but not
|
||||
LLM-natural — so they don't ship.
|
||||
- **Higher-rank polymorphism rejected at parse time.** Error
|
||||
message proposes the canonical workaround (two separate
|
||||
functions). LLM-friendly: clear cut over subtle codegen
|
||||
fallback.
|
||||
- **Heterogeneous containers via sum types, not `dyn Show`.**
|
||||
Same reasoning. Sum types are what the LLM would produce
|
||||
unprompted; type-erased existentials are not.
|
||||
|
||||
If the rule were inverted — "ship every feature a sufficiently
|
||||
sophisticated user might want" — 22a would commit to dictionary
|
||||
passing and existential types from day one, and AILang would
|
||||
gain the same dispatch overhead and codegen complexity that
|
||||
make general-purpose languages opaque to the optimizer. The
|
||||
rule cuts that off.
|
||||
|
||||
### Test state
|
||||
|
||||
288 / 0 / 3, unchanged. Documentation-only commit; no Rust,
|
||||
schema, or bench changes.
|
||||
|
||||
### JOURNAL queue
|
||||
|
||||
Unchanged from 21'g. Next dispatch is 22a (typeclass design
|
||||
iter), which is orchestrator-level work the orchestrator does
|
||||
directly: DESIGN.md typeclass section, instantiation strategy,
|
||||
schema nodes for `class` and `instance`, naming convention for
|
||||
monomorphised functions. Implementer iter (22b) follows after
|
||||
22a's design lands and is reviewed.
|
||||
|
||||
Reference in New Issue
Block a user