Brummel
138157767e
The skill-system migration (c1441f3) moved skills/ out of the repo to ~/dev/skills/, but the feature-acceptance contract's ratifying anchor still pointed at the now-gone `skills/brainstorm/SKILL.md`. `every_contract_names_a_resolvable_ratifying_test` in design_index_pin.rs (the test the honesty-rule wires to every contract row) caught it. Re-anchor to `CLAUDE.md` § "Feature acceptance: LLM utility" — that section in the in-tree project discipline file IS the ratification of the criterion; the brainstorm skill is the out-of-tree mechanism that applies it at spec time. Two edits in lockstep: design/INDEX.md row 81 and the "Ratified by:" line at the bottom of the contract body. Not iter-scoped (orthogonal to prep.3 of kernel-extension- mechanics, which landed in9339279).
80 lines
4.0 KiB
Markdown
80 lines
4.0 KiB
Markdown
# Feature-acceptance criterion
|
|
|
|
## Feature-acceptance criterion
|
|
|
|
A proposed feature ships only if all three 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.
|
|
|
|
3. **The feature reintroduces no bug class the core constraint exists
|
|
to eliminate.** Criterion 1 is necessary but does *not*
|
|
discriminate: an LLM reaches for *every* construct native to its
|
|
imperative training distribution, so "the LLM reaches for it" is
|
|
satisfied by exactly the constructs AILang most deliberately
|
|
refuses. A feature can pass 1 and 2 — LLMs reach for it unprompted,
|
|
and it removes redundancy — and still be a regression, because it
|
|
reinstates the error surface the pure core, local-reasoning, and
|
|
RC-acyclicity guarantees were built to remove. The decisive
|
|
question is whether the construct re-opens a class of mistakes
|
|
(iterated-mutable-state reasoning, silently-unbounded recursion,
|
|
reference cycles) that a foundational invariant — see
|
|
[language constraints](0015-language-constraints.md) — closes. If it does,
|
|
it is cut even when 1 and 2 hold — *or* it must be reshaped until
|
|
the bug class is structurally impossible rather than merely
|
|
discouraged. A documentation note is not a reshape; the
|
|
discriminator is whether the wrong code fails to typecheck, not
|
|
whether a guideline advises against it. Worked example: a bare
|
|
`while` over mutable state would pass criteria 1 and 2 yet fail
|
|
criterion 3 (it reinstates iterated-mutable-state reasoning the
|
|
pure core exists to remove); a hypothetical "all repetition is
|
|
either structurally-decreasing recursion over an acyclic ADT or
|
|
an explicit named loop" iteration story would, *if it could be
|
|
built without a documented-unenforced precondition*, pass all
|
|
three — and the fact that the 2026-05 attempt could not (it
|
|
forced a silent-divergence precondition; see
|
|
`docs/specs/0032-iteration-discipline-revert.md`) is itself
|
|
the bug-class-reintroduction discriminator working as intended.
|
|
|
|
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. LLM-author utility
|
|
(1, 2) is necessary; criterion 3 is the discriminator that keeps
|
|
utility from laundering the imperative paradigm back in one construct
|
|
at a time.
|
|
|
|
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.
|
|
|
|
Ratified by: `CLAUDE.md` § "Feature acceptance: LLM utility"
|
|
(in-tree project discipline). The brainstorm skill, which lives in
|
|
the `~/dev/skills/` plugin outside the repo, applies this criterion
|
|
at spec time.
|