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:
2026-05-09 10:59:28 +02:00
parent aea3758742
commit 338a4cd3fe
3 changed files with 138 additions and 0 deletions
+42
View File
@@ -61,6 +61,48 @@ everything that lands in git is English. This keeps diffs and tooling output
uniform and matches the audience for AILang (LLM authors), for whom English
is the default.
## Feature-acceptance criterion
A proposed feature ships only if both hold:
1. **An LLM author naturally produces code that uses it.** Without
prompting toward the feature, the LLM reaches for it as the clean
way to express the situation. If the feature is only used when
explicitly mentioned, it isn't earning its keep — the LLM is the
only author, and what the LLM doesn't reach for naturally is dead
surface area.
2. **The feature measurably improves correctness or removes
redundancy.** Either it eliminates a class of bugs structurally
(the schema forbids the wrong code), or it lets the LLM express the
same logic in fewer sites that have to stay consistent across
edits. Aesthetic appeal — "feels elegant", "is idiomatic" — does
not count.
This is the positive complement to the CLAUDE.md rule that
implementation effort is not a rationale: cost is not a reason *for* a
feature, and neither is human aesthetic preference. The only thing
that is, is LLM-author utility.
Two corollaries:
- **Human-attractive but LLM-neutral features are cut.** Point-free
style, operator overloading, implicit conversions, syntactic
shortcuts that hide structure. They reward human authors who enjoy
compression; they cost the LLM the explicit form it relies on to
keep RC, uniqueness, and effects locally legible.
- **Human-hostile but LLM-friendly features are kept.** JSON as
canonical authoring surface; mandatory mode annotations on every
fn parameter; mandatory top-level type signatures; explicit `clone`
for shared values. These cost a human author keystrokes; they let
the LLM reason locally without spending context window on
cross-references.
Empirically: if a feature is proposed and the LLM does not produce it
in unprompted code samples, the feature is proposed for the wrong
reason. The orchestrator's job is to notice that and cut.
## Decision 1: source = data, not text
A module is a JSON object with a fixed schema. There is no parser for