| name | right-size |
| description | Detailed right-sizing decision logic for a coding task, load this only when actually writing or changing code. The always-on rule in RULES.md is the one-paragraph summary; this is the full version. |
Right-sizing a coding task
This is the lazy-loaded detail behind the one always-on sentence ("Match the
solution to the requirement, no smaller, no larger"). Pull it in when a task is
actually a coding task; otherwise it costs tokens for nothing.
Step 1, climb the decision ladder
Stop at the first rung that holds:
- Delete the requirement. Can this not be built? (YAGNI) Half of
"right-sizing" is removing work, not shrinking it.
- Standard library. Does stdlib already do it? Use it.
- Platform feature. Use the native thing, don't wrap it. The browser, OS, or
runtime usually already has one:
<input type="date"> over a date-picker dep,
fetch over an HTTP client, Intl over a formatting lib, crypto.randomUUID()
over a uuid package. Reach for a wrapper only when the native API can't do it.
- Installed dependency. Already in the project's deps? Use it. Don't add a
new dep to save a few lines; do reach for one to remove real maintenance.
- One readable line. Can it be one line that needs no comment to decode?
- Minimum working code. Otherwise, the least code that fully meets the
requirement, including the parts below.
Step 2, run the under-engineering checks
Minimalism's blind spot. Before "done", confirm you didn't cut a corner that's
actually part of the requirement:
| Check | Ask | If it applies and you skipped it |
|---|
| Inputs | Empty / malformed / out-of-range handled at trust boundaries? | Add validation or mark occam: |
| Scale | Stays correct as input grows? (unbounded loops, pagination, memory) | Bound it or mark occam: |
| Failure | I/O, network, external calls fail without data loss? | Handle it, never occam: data loss |
| Concurrency | Shared state two callers can corrupt? | Guard it or mark occam: |
| Unstated | What did the user obviously mean but not say? | Build that too |
Step 3, never shortcut these
These are part of the requirement, not extras. Efficiency is never the excuse:
input validation at trust boundaries, error handling that prevents data loss,
security (authz / secrets / injection / SSRF), accessibility, and anything the
user explicitly asked for.
Step 4, mark intentional simplifications
// occam: <what's simplified>, fine until <ceiling>; <upgrade path> when it isn't
State the ceiling (when it breaks) and the upgrade path. /occam-debt harvests
these so a deliberate shortcut stays visible instead of becoming a silent bug.
Pick an intensity (ultra | full | lite)
Set how hard you scrutinize for over-build, matched to where the risk lives. The
dial tunes effort only; Step 3's floor holds at every level.
- ultra, greenfield. A blank file breeds abstractions nobody asked for, so
apply the harshest YAGNI: delete requirements first, climb the whole ladder,
refuse premature options and layers.
- full (default), normal changes. Ladder plus checks as written.
- lite, fragile or unfamiliar existing code. Smallest surgical edit that meets
the requirement; don't refactor or tidy code you weren't asked to touch.
Auto-select when nothing sets the level: new or near-empty file is ultra, an
edit to fragile or unfamiliar existing code is lite, otherwise full. A command
flag (/occam:review <level>) or an orchestrator's Build stage can override.
Orthogonal to model routing (model-routing/SKILL.md): intensity is scrutiny,
routing is which model. The Build stage of an orchestrator sets this per task,
ultra for greenfield, lite when patching fragile code, full otherwise.
Two failure modes, equally wrong
- Over-engineering, a framework for a 10-line problem, premature config,
abstractions nobody asked for. Climb the ladder; most of this disappears.
- Under-engineering, the clever one-liner no one can maintain, the dropped
edge case, the missing retry. The Step 2 checks catch this.
Right-sizing is hitting neither. When two solutions tie on size, pick the more
readable and less fragile one.
