Vivswan Code Standards
House standards for code and the artifacts around it. Apply them while writing; check them while reviewing.
Where a standard has a canonical case (the specimen that set the rule), it is stated inline or in the standard's references/ file: the concrete case recalls better than the rule. The references/ file named under each standard carries the full detail: the why, the how-to-apply list, and the boundaries and exceptions.
The Standards
Fix the class, not the instance
A systemic problem gets a root fix that makes recurrence impossible, never only a fix of the case at hand: the /never-twice skill owns this rule and its response ladder; specimen and full detail in references/design.md.
Guard recurring problems with tests
A problem that recurs, or plausibly will, ships with a test, tripwire, or pipeline fix that catches it at the source: rung 2 of the /never-twice ladder; full detail, including the guard-outside-your-reach case, in references/design.md.
General-purpose over special-case
Parameterize the axis that keeps changing instead of hardcoding today's instance.
Specimen: a safety classifier whose rulebook kept changing was built as a classifier FACTORY with the rubric as an input. Any rubric change produces a new classifier for free, and the same machinery serves uses beyond safety.
Full detail, including the one-pipeline-per-concept rule (the page that grew three visibly diverging error-band renderers) and where DRY stops: references/design.md.
Maintainability over effort
Code quality outweighs diff size and effort spent. A big refactor is always better than a fix done the wrong way: wrong-shaped fixes compound into tech debt.
- Take the larger refactor when it is cleaner, and reduce complexity.
- Enforce invariants in types rather than repeated checks (see the
/no-invalid-statesskill). - Use assertions to pin invariants the type system cannot carry: one assertion at a boundary removes whole families of downstream edge-case handling.
Specimen: a documented workaround hybrid was reworked outright rather than kept. Never preserve a workaround to keep a diff small.
Full detail: references/design.md.
Minimum standard for tests
A floor every test clears, not a recipe for which tests to write: fuzzing, property-based, integration, and other richer tests are welcome, and each of them still meets this bar. A test asserts a whole outcome, not one field of it. Agents drift toward many small weak tests; the fix is tests that each pin a whole outcome, which leaves fewer of them as a side effect, not a goal.
- Delete tests that only assert a shape, a type, or that something exists. If that fact matters, assert it inside a test that also checks the value.
- When hand-written cases differ only along one input axis, replace them with one parametrized case list.
- Prove each guard test: show it failing on the bug it guards, and for that reason. Reintroducing the bug is the standard form; a pre-fix red run is the same control.
Specimen: an extractor had fifteen tests each asserting one key of the returned dict. Folded into one parametrized test pinning the whole dict per scenario, the file went from 81 test functions to 44 while every one of the seven bugs the suite existed to catch still failed when reintroduced. A test that ignores a column cannot catch a regression in it.
Full detail: references/tests.md.
Comments only for what code cannot show
Comments exist only for non-obvious constraints, cross-file invariants, and external-system quirks; the code is the single source of truth.
- Keep them SHORT: one to three lines.
- Delete comments that restate the code outright.
- A comment grown into a paragraph holds either narration (delete it) or a workaround defense (fix the code, not the comment).
Full detail, including the TODO ban: references/comments.md.
No barrel files or pass-through functions
Delete these and repoint the importers or callers at the defining module or real function:
- an import-only index file
- a "keep old importers compiling" re-export left after a move
- a function whose whole body forwards to another function without adding anything
A wrapper earns its existence only by adding something real (a default, a conversion, error mapping, an injected dependency, a narrowed type). In Python, __init__.py stays EMPTY unless absolutely necessary: re-exports there are the same barrel.
Full detail, including the migration-staging exception and what is not a barrel: references/structure.md.
No planning references in code
Code and comments never reference planning artifacts: work-package names, spike or phase labels, plan codenames, audit finding numbers. The next reader has the code, not the plan.
Specimen: a comment like "WP-B spike, part 2:" has no meaning outside the planning; comments describe purpose and constraints, not where the code came from.
Full detail: references/comments.md.
Lean AGENTS.md
Agent instruction files (AGENTS.md, CLAUDE.md) hold only project essentials: purpose, toolchain entry points, conventions CI enforces, safety constraints, and pointers. Cut anything an agent could learn by reading the code and keep a one-line pointer instead: duplicated detail drifts and then misleads; a pointer cannot drift.
Full detail: references/artifacts.md.
Commit messages carry content only
Commit and PR messages state what changed and why, following the repo's subject conventions. No AI or tool attribution lines and no hard wrapping of the body at 72 columns (a wrapped body renders as ragged mid-sentence breaks in GitHub's soft-wrapping UI).
Specimen of the one sanctioned attribution, human community credit in repos that take contributions: fix: ... (#NN, thanks @user) in the subject, Co-authored-by: trailers for humans whose code landed. Credit for people, never for tools.
Full detail, including the email-patch exception: references/artifacts.md.
No blobs of text
Docs, READMEs, reports, and PR text use scannable structure: bullets for facts, tables for enumerations, numbered steps for flows, paragraphs of 1-3 sentences. When the content is enumerable, enumerate it. Short explanatory paragraphs are fine; wall-of-text prose where structure would scan better is not.
Full detail: references/artifacts.md.
Review Criteria
- Instance-only fixes: does the change prevent recurrence (test, type, tooling), or just patch the case at hand?
- A recurring or recurrence-prone problem fixed again without a guard test, tripwire, or pipeline fix (or a proposal to the user when the pipeline is out of reach).
- Tests that assert only a shape, a type, or that something exists; hand-written test functions that differ only along one input axis and should be one parametrized case list; a guard test never seen failing on the bug it guards.
- Special-casing: a new near-copy of existing logic where the varying axis should be a parameter.
- Complexity added to keep a diff small: flags, nesting, or repeated checks where a cleaner refactor or a stronger type was available (the
/no-invalid-statesskill covers the type-level fix). - Comments that restate the code, and paragraph-long comments justifying workarounds (flag the underlying code, not the comment alone).
- Barrel files, re-export shims, or pass-through functions that only forward to another function or module.
- Planning artifacts (work packages, phases, codenames, finding numbers) referenced in code or comments.
- AGENTS.md or CLAUDE.md edits that duplicate implementation detail derivable from the code.
- Attribution lines or hard-wrapped bodies in commit messages and PR descriptions.
- Wall-of-text prose in docs, reports, or PR text where bullets, tables, or numbered steps would scan better.
Triage findings against the standards above; each criterion maps to one.
Workflow
- Writing code: apply the standards as you go; they are cheaper at write time than at review time.
- Reviewing: check the Review Criteria, cite the specific standard in each finding, and prefer suggesting the class fix over the instance patch.
- When a standard needs its boundaries (what counts, what is exempt, how far to take it), load the matching
references/file before acting on it. - When a finding calls for enforcing invariants in the type system (lifecycle flags, must-call-X-before-Y ordering, fields that must appear together), apply the
/no-invalid-statesskill for the refactor itself. - When a standard conflicts with an explicit user or project decision, follow the decision and record which standard was consciously set aside.
References
references/design.md: fix the class, general-purpose over special-case (one pipeline per concept, DRY boundaries), maintainability over effortreferences/tests.md: the minimum standard for tests, what counts as weak, proving a guard test with a negative controlreferences/comments.md: the comment rules in full, the TODO ban, planning referencesreferences/structure.md: barrels, compatibility re-exports, escort functions, migration stagingreferences/artifacts.md: lean AGENTS.md, content-only commit messages and their two exceptions