elegant-code

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:

1. A shared vocabulary (the rungs, the floor) that review

skills can point at, so "you skipped rung 2" is a concrete,

auditable note.

1. Consistency: the ladder is applied every time, not just

when the model happens to think of it.

1. 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.

# JS/TS: unused files, exports, dependencies
command -v knip >/dev/null && knip || echo "knip absent; skipping"

# Python: dead code
command -v vulture >/dev/null && vulture . || echo "vulture absent; skipping"

# Rust: unused dependencies (nightly)
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

• [ ] Each addition was walked down the ladder, and the chosen

rung is stated (for example, "rung 2: stdlib zfill").

• [ ] Any new dependency passed Skill(imbue:dependency-verification)

and reuse of an installed dependency was ruled out first.

• [ ] Every untrusted input has its negligence-floor guard present

(validation, authorization, error handling).

• [ ] A deletion tool was run, or its absence was noted, and no

flagged candidate that is a guard was deleted.