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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user