demand-elegance · git:20260519.40bb110 · 2026-05-19 · sha256 437891b200fc6765

demand-elegance git:20260519.40bb110A

Immutable. This exact content never changes and is served at /api/v1/blob/437891b200fc6765.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_vmkkdapoo33lkwxy/437891b200fc6765e4f3c14b2334053abfa6a6880dbd132e6faa07ae944e8871.json

Then /plugin install demand-elegance@markdownregistry-vmkkdapoo33lkwxy in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: demand-elegance
description: Challenges hacky fixes on non-trivial changes.
tier: core
category: discipline
created_by: human
platforms: [windows, macos, linux]
tags: [quality, design, simplicity]
author: Andreas Wasita (@andreaswasita)
---

# Demand Elegance Skill

Forces the agent to challenge its own non-trivial diff before presenting it: fewer moving parts, standard patterns over custom abstractions, boring over clever. Does NOT apply to typos, one-line fixes, or hotfixes — over-engineering trivial work is the failure mode this skill explicitly avoids.

## When to Use

- A fix feels hacky, fragile, or "barely working".
- Multiple solutions exist and the tradeoffs aren't obvious.
- The diff is large and includes infrastructure the original task didn't ask for.
- Refactoring with simplification as the explicit goal.
- Self-review before presenting any non-trivial solution.
- NOT for: typos, one-line bugfixes, comment edits, formatting, production hotfires.

## Prerequisites

- A working solution (or near-working) to challenge — don't run this on a blank canvas.
- The full diff visible (`git diff` via the `powershell` tool).
- Willingness to throw work away if a simpler approach exists.

## How to Run

```text
1. Confirm the change is non-trivial. If trivial, skip — see Pitfalls.
2. Run the Elegance Check (4 questions in Procedure §1).
3. Apply the Simplicity Ladder (Procedure §2) to choose between options.
4. Self-review the diff as if it were someone else's PR.
5. If hacky, restart with the elegant approach — don't deodorize the smell.
```

## Quick Reference

| Question | If answer is "yes" → action |
|---|---|
| Is there a more elegant way? | Try it before shipping. |
| Knowing what I know now, would I build it this way? | If no, refactor before presenting. |
| Can I reduce moving parts? | Cut them. |
| Would a senior engineer raise an eyebrow? | They would. Fix it. |

| Choose | Over |
|---|---|
| Fewer lines | More lines (all else equal) |
| Standard patterns | Custom abstractions |
| Fewer dependencies | More dependencies |
| Readable | Clever |
| Boring & correct | Exciting & fragile |

## Procedure

### Step 1: The Elegance Check

For non-trivial work, before presenting the diff, ask in order:

1. Is there a more elegant way?
2. Knowing everything I know now, would I build it this way?
3. Can I reduce the number of moving parts?
4. Would a senior reviewer raise an eyebrow at this?

A "yes" to any means: pause and try the simpler path.

### Step 2: The Simplicity Ladder

When picking between solutions, prefer the upper rungs:

1. No code change (the bug isn't a bug, or the requirement is wrong).
2. Configuration change.
3. Small, local code change inside one function.
4. Localized refactor inside one module.
5. Cross-module change with explicit motivation.
6. New abstraction (only if 1–5 are insufficient).

If you land on rung 6, justify why 1–5 do not work in a comment or in `tasks/todo.md`.

### Step 3: Self-Review the Diff

Run `git diff` via the `powershell` tool and read your own diff as if reviewing a stranger's PR. Identify the smelliest part — there is always one. Ask whether that smell can be eliminated, not just covered up.

### Step 4: Restart If Hacky

If the diff still feels hacky after Step 3, throw it away and start over with the simpler approach. Resist the sunk-cost reflex.

A useful self-prompt: *"Knowing everything I know now, implement the elegant solution."*

## Pitfalls

- **DO NOT** run this skill on trivial changes. A typo fix doesn't need an architecture review.
- **DO NOT** premature-abstract. Build for the requirements that exist, not the ones you imagine.
- **DO NOT** gold-plate. The user asked for a button fix, not a component-system redesign.
- **DO NOT** confuse cleverness with elegance. If you need a comment to explain what (not why) the code does, it's too clever.
- **DO NOT** apply during production hotfires. Stabilize first; log a `tasks/lessons.md` entry to revisit.
- **DO NOT** deodorize a smell — eliminate it. Wrapping bad code in a clean interface still leaves bad code.

## Verification

- [ ] Diff size is justified by the task description in `tasks/todo.md`.
- [ ] No new abstractions without explicit justification.
- [ ] No new dependencies without explicit justification.
- [ ] Self-review pass completed (`git diff` read end-to-end).
- [ ] No `tasks/lessons.md` entry tagged `over-engineering` for this task.