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.
4.1 KiB
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.