@crossplatformai/skills/skills/post-build-ship/references/elegant-code.md

Reusable Agent Skills for CrossPlatform.ai projects.

# Elegant Code

This is a Post.Build.Ship reference, not a standalone skill.

Use this reference when `post`, `build`, or `ship` is already active and the work involves refactors, abstraction design, meaningful duplication, WET code, over-engineered code, code smells, simplifying complex flows, primitive or API design, or deciding whether repeated logic should be unified.

This reference supplements Post.Build.Ship. It preserves Authorizing User authority, observable
acceptance, material boundaries, fail-fast approvals, proportionate QA, ownership, and Ship safety.
It adds no mandatory review or presentation fields.

## The Standard

Elegant code is simple and powerful. It reduces a complex process to first principles, then names the small set of primitives that make the larger system easier to hold.

Think of the periodic table: a complex world becomes understandable because it is organized around stable elements and relationships. Elegant code does the same for a codebase. It does not hide complexity behind cleverness; it exposes the right elements so the rest can compose.

Use established engineering terms intentionally. `DRY`, `WET`, `over-engineered`, `code smell`, `first principles`, `simple and powerful`, and `dependency hell` are useful shorthand. Keep the vocabulary when it carries real judgment, and ground it in concrete behavior so it does not become vague style preference.

## DRY After Clarity

Prefer DRY code over WET code when the shared concept is real, nameable, and stable.

Do not unify two things only because they look alike today. If they answer to different reasons to change, forcing them through one abstraction creates false sameness and future friction.

Good abstraction removes a concept the maintainer no longer has to track. It reduces drift, makes invalid states harder, and leaves call sites easier to read without hiding important behavior.

Small local duplication is acceptable when an abstraction would be premature, obscure intent, or create dependency hell. WET code becomes a problem when repeated decisions can drift, fixes must be copied by hand, or the same rule is expressed in several places without one clear owner.

## Smells And Over-Engineering

A code smell is a signal to investigate, not automatic permission to refactor outside scope. Surface the smell, name the evidence, and explain what simplification would remove.

Over-engineered code adds ceremony, indirection, generic machinery, or configuration surface that does not make the system simpler or more powerful. It may look sophisticated while increasing the number of concepts a maintainer must hold.

Elegant code should feel smaller after you understand it. If a change adds layers, adapters, options, or abstractions, be able to say what concept disappeared, what duplication stopped drifting, or what failure mode became harder.

## Scope Discipline

When an elegant simplification is inside the approved scope, prefer the simple primitive over repeated special cases or broad machinery.

When the simplification is outside scope, say so. Record the smell or simplification opportunity as a risk or follow-up instead of silently expanding the task.

For an in-scope refactor or simplification, stop and report completion once the approved objective,
observable acceptance, and required proof are complete. Defer unrelated cleanup, generalized
abstractions, speculative edge-case support, and optional polish as follow-ups. A useful
maintainability improvement that supports the objective is not out of scope merely because it adds
coherent structure or more than the fewest possible lines.

This stopping rule does not cover a known correctness, safety, acceptance, or required-QA gap:
continue the work or block on it. A deferred edge case must still fail loudly under
`references/fail-fast.md`; do not weaken tests, suppress failures, conceal known debt, add an
unapproved fallback, or bypass user intent to finish.

Voltaire wrote the familiar maxim in _La Bégueule_ (1772): “Le mieux est l’ennemi du bien” (“The
better is the enemy of the good”), commonly rendered as “Perfect is the enemy of good.” He presents
it as something said by “a wise Italian,” so attribute the wording to Voltaire without claiming he
coined it. [Voltaire, _La Bégueule_ (1772)](https://fr.wikisource.org/wiki/Contes_en_vers_%28Voltaire%29/La_B%C3%A9gueule)

Apply that principle without lowering the bar: do not let elegance become perfectionism. The goal is
not clever code, short code, or abstract code. The goal is code with fewer moving parts, clearer
primitives, less drift, and more power per concept.