# PRINCIPLES.md — the four engineering principles

These govern all Corviduo work and apply equally when reviewing code, designing probes, or critiquing a research direction. Apply them as the lodestar against which every recommendation, finding, or pushback is measured.

Common spine: **fitness-for-purpose**. Each principle rejects a different substitute goal that disguises itself as virtue.

## 1. Excellence over uniqueness

Pick the shape that's right for the problem, not the shape that's new.

If uniqueness is a byproduct of excellence, fine — don't target it. The bias to flag: novel-for-novel's-sake architectures, hand-rolled implementations when a stable library exists, exotic patterns ("CRDT! Event sourcing! Effect system!") where a plain table and a function would do.

**Review heuristic**: when a design choice is unusual, ask *why this and not the conventional shape?* If the answer is "it felt cleaner" or "I wanted to try X," reject. If the answer is a specific property of the problem that the conventional shape doesn't satisfy, accept.

## 2. Explicit over implicit

Make load-bearing assumptions, constraints, and coupling visible.

Idiomatic implicitness (language conventions, well-known protocols, in-tree patterns the team uses everywhere) is fine. The rule targets *invisible* implicitness — the assumption nobody documented, the coupling that lives in two files but isn't named anywhere, the constraint that exists only in someone's head.

Cost of explicitness: verbosity. Cost of invisible implicitness: undetectable coupling. Pay the cost where auditability beats the tax.

**Review heuristic**: when reading a diff, ask *what does this code assume that isn't stated?* Hidden assumptions are bugs in waiting. Surface them in review even if the code is otherwise fine — naming the assumption is worth the round-trip.

## 3. Elegance is a byproduct, not a target

Excellent engineering often produces elegant results; targeting elegance directly tends to produce cleverness, which is a different thing.

Cleverness shows up as: obscure one-liners where five lines would be readable; deeply nested type-system tricks where a plain struct would suffice; "look how minimal this is" framings where the minimality came at the cost of debuggability.

**Review heuristic**: ask *is this fit-for-purpose, debuggable, consistent with how the rest of the codebase reads?* Not *does it feel nice?*

## 4. Action-relevance over thoroughness

Before investigating, ask whether the answer would change the action. If both outcomes lead to the same default, skip the question.

This applies equally to:
- **Code review**: don't flag bikesheddy preferences that wouldn't change whether you'd merge.
- **Research design**: don't probe what won't change behavior. If H07 confirmed and H07 rejected both lead to "ship D anyway," H07 isn't worth probing yet.
- **Pre-call analysis**: don't enumerate every possible mitigation; enumerate the ones whose adoption you'd actually recommend differently.

**Review heuristic**: at the end of a review, ask *if every comment I'm about to write were resolved exactly as I wrote it, would the diff land in a meaningfully different shape?* If no, cut the comment.

## How these compose

The principles are not a checklist; they are an attitude. When a recommendation seems to require trading one against another, surface the trade explicitly rather than pretending the trade isn't there:

- Excellence sometimes argues for an unfamiliar shape (#1 in tension with the conventional-shape bias of #1 reading the other way). The arbiter is fitness — *for this problem*.
- Explicitness sometimes adds verbosity that hurts elegance (#2 vs #3). The arbiter is *whose downstream cost is higher* — readers of the explicit version, or readers of the implicit version when something breaks.
- Thoroughness without action-relevance feels like care but is noise (#4 trumping naïve diligence). The arbiter is *would this answer change a decision*.

In all cases the final question is the same: **is the shape fit-for-purpose?** Reach for that question before reaching for the principles individually.