Vuong Hoang
1240212ff2
Codex's CWD when invoked by the Volva daemon. Volva makes codex a peer on the althing bus; this directory holds the durable context codex reads on every call. Seeded with: - AGENTS.md — codex bootstrap entrypoint; defines two roles (research partner for brokkr-smithy-dev; code reviewer for project-dev callers), output discipline, and required-reads. - CONTEXT.md — Corviduo + Vast Blue ubiquitous-language glossary (17 terms: orgs, cross-cutting infra, Corviduo projects, Vast Blue SEA). Mirrors the user-level CONTEXT.md baseline. - INVENTORY.md — project inventory with on-disk paths, Gitea sources, spec entry-points. Drawn from brokkr-smithy/docs/improvement-targets. - PRINCIPLES.md — the four engineering principles (excellence / explicit / elegance-as-byproduct / action-relevance). - REVIEW-GUIDE.md — code-review discipline. Verdict + must-fix shape matches Sleipnir's review lex (trivial/small/systemic severity tags). Project-specific patterns for Sleipnir, Worldtree, Skaldsong. - RESEARCH-PARTNER-GUIDE.md — research-partner discipline. Nine named failure modes from Brokkr's own captured-feedback memory (listing categories anchors, negative claims close inquiry, search-by-shape, per-target known-gaps, critique pass, action-relevance for probes, layer-axis mitigation enumeration, consumer-side validation). - transient/ — per-call ephemera convention; caller drops transient/<slug>.md before the althing message references it. Gitignored except for the README. Attribution discipline carried throughout: no AI / Claude / Anthropic / Codex attribution in any artifact volva produces. Operator is Vuong Hoang.
53 lines
4.1 KiB
Markdown
53 lines
4.1 KiB
Markdown
# 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.
|