Elegant Code
Write the minimal, elegant code that fully solves the problem:
its performance, its edge cases, and its failure cases. Minimal
is not fewest lines. It is no incidental complexity, with
nothing essential omitted.
What this skill is (and is not)
This skill codifies a discipline that strong models already
exhibit some of the time. Its value is not teaching a missing
capability. Its value is three things:
- A shared vocabulary (the rungs, the floor) that review
skills can point at, so "you skipped rung 2" is a concrete,
auditable note.
- Consistency: the ladder is applied every time, not just
when the model happens to think of it.
- A guard: the negligence floor below is never traded away
for brevity.
It is the generative counterpart to the review-side contract in
leyline:additive-bias-defense.
When To Use
- Before adding a function, file, class, abstraction, or
dependency.
- When choosing between reuse and writing new code.
- When auditing a diff for lines that can be deleted.
When NOT To Use
- Throwaway scripts or one-time migrations where review cost is
near zero.
- Cases where the negligence floor (below) is in play: there,
add the guard first and optimize length second.
The Decision Ladder
Walk the rungs in order. Climb down only when the current rung
does not hold. Stop at the first rung that solves the problem.
| # | Rung | Ask | Stop here when | Example |
|---|
| 1 | Need-to-exist | Does this need to exist at all? | The requirement is speculative or already met. Delete or defer. | "Config loader for a value used once" -> inline the value |
| 2 | Builtin / stdlib | Can a language builtin or the standard library do it? | The stdlib covers it. | str.zfill, f"{n:05d}", pathlib, itertools |
| 3 | Native platform | Is there a native platform or framework feature? | The platform already ships it. | URLSession retry, fetch, framework validators |
| 4 | Installed dependency | Is an already-installed, audited dependency enough? | A dep in the lockfile covers it. | reuse requests/urllib3 backoff before adding tenacity |
| 5 | A few lines | Can it be one line or a small explicit block? | A short, obvious block solves it. | a 20-line retry loop over a retry framework |
A new dependency is the last resort, below rung 5, not rung 4.
Before adding one, verify it actually exists and is safe with
Skill(imbue:dependency-verification): generated code imports
non-existent packages at measurable rates, and recurring fake
names enable slopsquatting (arXiv 2406.10279, USENIX 2025).
Prefer reuse of an installed, audited dependency over both a new
dependency and a hand-rolled reinvention. Zero-dependency code is
not automatically cheaper: it relocates the maintenance and bug
surface into your own tree (see references/sources.md).
What minimal must still cover
Minimal does not mean fewest lines. It means no incidental
complexity, with nothing essential omitted. The decision ladder
removes incidental code: reinvention, speculative abstraction,
needless dependencies. Three things are essential and are never
traded for brevity.
Correctness and safety (the negligence floor)
Never cut for brevity. A review must never propose deleting these
as "extra code":
- Trust-boundary and input validation on untrusted data.
- Authorization checks (permission gates, row-level security).
- Data-loss handling (transactions, idempotency keys, retries
that cannot double-charge).
- Error handling on fallible I/O.
- Security-relevant paths (authn, secrets, crypto).
- Accessibility.
This floor is evidence-backed, not a slogan. The dangerous
failure mode in generated code is omission: roughly 45% of
AI-generated samples carry a security flaw, with a measured
~2.74x vulnerability rate versus human code, driven by missing
validation, missing authorization, and missing error handling
(Veracode 2025). CVE-2025-48757 is a concrete case: generated
schemas shipped without row-level security policies. An absent
guard is not zero bugs. It is one latent bug per untrusted input.
Performance
Handle the expected input size and the hot path: avoid accidental
quadratic loops, N+1 queries, and unbounded memory growth. Do not
micro-optimize speculatively. Premature, speculative optimization
is itself incidental complexity, so YAGNI applies to performance
too. Optimize what the known input size or a profiler justifies,
not what feels fast.
Edge and negative cases
The negative path is part of the spec, not extra code. Cover
empty, None, and zero inputs; boundary values; malformed or
hostile input; partial failure and timeouts; and concurrency
where it applies. Code that handles only the happy path is not
minimal. It is unfinished.
Elegance, not terseness
Prefer the clearest expression a reader can verify, not the
cleverest or the shortest. Terseness and cleverness raise review
cost and defect risk: dense one-liners hide edge cases, and
correctness-only evaluation misses the maintainability they cost
(arXiv 2407.11470). Elegance is minimal incidental complexity
plus maximal clarity, which is not the same as minimal characters.
Why minimal (stated honestly)
The case for less code rests on surfaces you can measure, not on
a clean "fewer lines means fewer bugs" law. That law is not
empirically settled: studies find weak or absent correlation
between complexity metrics and defect rate (arXiv 1912.01142,
1912.04014). Argue instead from:
- Attack surface: fewer imports and branches are fewer places
for a known failure mode (hallucinated import, unhandled path).
- Review cost: a document, and a diff, costs the sum of its
readers' time. Less code is less to review correctly.
- Token and latency cost: shorter output is cheaper to
generate and faster to run.
- Iteration risk: additive self-refinement is not free. One
study measured a +37.6% rise in critical vulnerabilities after
five refinement rounds (arXiv 2506.11022). Bias the loop toward
deletion, then stop.
Verification hooks
After writing, cross-check deletability with real tools instead
of guessing from the diff. Gate each behind command -v and fall
back cleanly when absent.
command -v knip >/dev/null && knip || echo "knip absent; skipping"
command -v vulture >/dev/null && vulture . || echo "vulture absent; skipping"
command -v cargo-udeps >/dev/null && cargo +nightly udeps \
|| echo "cargo-udeps absent; skipping"
Treat tool output as candidates, not verdicts. Code reachable
only via reflection, dynamic dispatch, or framework magic can be
flagged as dead while being live. Cross-check against the
negligence floor before deleting anything.
How this composes
| Skill | Relationship |
|---|
imbue:dependency-verification | Rung 4/new-dep gate: confirm a package exists before adding it |
leyline:additive-bias-defense | Review-side burden-of-proof contract this skill generates against |
conserve:code-quality-principles | KISS/YAGNI principles this ladder operationalizes pre-code |
conserve:unbloat | Whole-codebase cleanup (this skill is per-change) |
imbue:scope-guard | Feature-level worthiness (this skill is line and dependency level) |
pensive:harden | Security review that enforces the negligence floor |
The /conserve:elegant-code-review command applies this ladder to
the current working diff.
Exit Criteria
