/elegant-code

name: elegant-code
description: Guide minimal code via a decision ladder with full safety, edge, and negative-case coverage. Use when adding code, choosing a dependency, or auditing a diff.
alwaysApply: false
category: conservation
tags:
- minimalism
- yagni
- decision-ladder
- dependency-discipline
- additive-bias
tools: []
complexity: low
estimated_tokens: 900

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. 2. **Consistency**: the ladder is applied every time, not just when the model happens to think of it. 3. 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 | Already in this repo | Does this codebase already do this somewhere? | A helper, module or convention here covers it. Reuse it. | an existing `estimate_tokens` before writing another | | 3 | Builtin / stdlib | Can a language builtin or the standard library do it? | The stdlib covers it. | `str.zfill`, `f"{n:05d}"`, `pathlib`, `itertools` | | 4 | Native platform | Is there a native platform or framework feature? | The platform already ships it. | `URLSession` retry, `fetch`, framework validators | | 5 | Installed dependency | Is an already-installed, audited dependency enough? | A dep in the lockfile covers it. | reuse `requests`/`urllib3` backoff before adding `tenacity` | | 6 | 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 |

Rung 2: one model per concern

Search before writing: `rg` for the function, the concept and its likely names. Rung 2 sits above the stdlib because a second way of doing something the codebase already does is a redundant model. Each one is locally valid, and every later change must translate between them. Measured agent adoption leaves complexity raised after the velocity gain fades (`docs/knowledge-corpus/decoherence.md`).

• Reuse the model the codebase already uses for the concern, even when

the stdlib offers a shorter spelling.

• Before reusing it, name what rungs 3 to 5 would do for the concern

(stdlib, native platform, installed dependency) and compare the contracts. The same contract in a different spelling is reused as it is. A contract that differs with a recorded reason is reused, and the reuse cites that reason. A contract that differs with no recorded reason is raised with both models named before it spreads to new code. A departure is an input the two handle differently: a copied version key in minister ranked `1.10.1-rc1` below `1.10.0`.

• When a migration is in flight, new code uses the target pattern.

Never copy the superseded variant, even when it is the majority of call sites.

• An addition that gives a concern a second implementation either

retires the first in the same change or records why both must stand (in the commit body, or the module docstring when it must outlive the commit).

• When the existing model is wrong for the case, say so and ask. Do

not quietly start a parallel one.

A *new* dependency is the last resort, below rung 6. 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 c