Skip to content

nWave-ai/nWave / nWave/skills/nw-code-craftsmanship

nw-code-craftsmanship

Unverified

Load when writing or changing production code in craft; per-unit rules, failure messages, security, recovery, performance, honest closing statement.

Code craftsmanship

Before writing a unit

  1. Search for an existing owner of the responsibility (by what it decides and who consumes it). Reuse or extend it; create a new one only when you can name the incompatibility.
  2. Give each fact, rule or config value one owner. Two units deciding the same fact are a defect even if the code differs; look-alikes that answer different questions stay separate.
  3. Generalize (abstraction, plugin, framework) only when a second real caller needs it now.
  4. Follow the design already chosen; if two owners compete for a rule, stop and raise it to the design owner instead of picking one.
  5. Follow the paradigm of the touched code; state the reason in the closing statement for any unit in another paradigm.

Writing each unit

  1. Name from the domain language, never Manager, Helper, mechanics. One unit = one reason to change, one responsibility visible from its name.
  2. State what the domain decides (expressions, pipelines, polymorphism), not bookkeeping.
  3. Keep state private; change it only through the owner's methods; keep data with the behaviour that uses it; expose no internal type across a boundary.
  4. When unit A reads unit B's data to decide, move the decision into B and send B a message.
  5. Two units sharing a position, literal, value meaning, algorithm or call order: replace by a named type, a named constant or one shared owner.
  6. Give a concept its own type when it can be confused with another, when a type can exclude invalid states, or when it owns a rule; its constructor refuses the invalid value. A native type that already says this stays native.
  7. At deliberate boundaries use precise records, unions or result types. Document, at the boundary, every generic payload (dict, Any, object) you add.
  8. Keep business decisions apart from SQL, transport and filesystem code; dependencies point inward through ports; inject collaborators.
  9. Functional code: pure core, thin effect shell (read, decide, write); the core never calls the shell.
  10. A driving or driven port exposes no private structure.

Failure messages

  1. Every refusal or failure you add states WHAT failed (the violated invariant), WHY (the cause), and HOW to fix, naming the concrete fix and the command or tool that produces a valid input.
  2. Include every fact the rejecting code already holds that the reader needs: the offending value and where it lives (file, line, field), the limit it broke.
  3. A validator over several inputs collects every independent defect and reports them all in one pass; checks that depend on another say they did not run.
  4. Run the remedy the message names; it must lead to an accepted input.
  5. Return every domain outcome in the return type; raise only for programming errors.
  6. Each failure ends in correct recovery, a loud refusal or INDETERMINATE, never a silent wrong success. Could-not-verify is a third result and reaches the summary.

Security and portability

  1. Parse untrusted input with schema validation at the trust boundary before use; never deserialize it into an arbitrary object (no pickle, no yaml.load).
  2. Normalise untrusted paths (resolve()) and check they stay inside the allowed root.
  3. Pass untrusted data to commands, queries and templates only as arguments: subprocess.run([..]) without shell, cursor.execute("... ?", (v,)), never string-built syntax.
  4. Never log or print a secret or commit a secret literal; read secrets from environment or store.
  5. Security defaults deny on error and grant least privilege; looser settings need explicit opt-in; check access on every request. A missing or newly added security scanner yields failure or INDETERMINATE, never a silent pass.
  6. Make each read-check-write atomic where a race breaks an invariant (open(p, "x"), rename, lock, transaction).

Recovery

  1. An operation promised idempotent or recoverable must reach the same final state when re-run after interruption, with no duplicate or half-applied effect (write temp then rename; upsert).
  2. When you change persisted data, keep a way back (revert or stated partial-rollback plan), or list it as unverified in the closing statement.
  3. For each failure point or bypass the design names, have a test observe the degraded outcome, or state in the closing statement why it is unreachable. When an assumption (dependency down, input twice, step interrupted) is negated, the code refuses loudly or degrades as documented.
  4. Adapter fault-injection tests (storage down, interrupted or double write, crash, concurrent writers) go in an infrastructure suite the default run excludes, and only where the human granted it.
  5. A rollback or degradation trigger is a stated measurable value that a check can trip.

Performance

  1. Avoid allocation, copying, repeated I/O and quadratic work on hot paths.
  2. Claim a speedup only with a re-runnable before/after measurement; each performance threshold you hard-code comes from a stated requirement.

Tests you add

  1. The oracle is not yours to edit. Add a unit test only when the oracle cannot go green without it, and only in the owned test paths.
  2. Every refusal or check you add gets one assertion that fails on a constructed violation; probe once by re-injecting the violation, then restore.
  3. A count assertion names its population and compares to it (len(found) == len(expected_ids)); a partition asserts that its parts sum to the whole; "nothing found" differs in output from a broken case.

File layout

  1. One type per file. A file holds one type and the methods that belong to it. In new code each type gets its own file. An existing file with several types is brought to this whole section only when DESIGN declares a prefactoring move for it because the slice changes it; execute that move as declared, in a separate commit before the behaviour change, and leave every other existing file as it is.
  2. Folders group types by concept inside the hexagonal layout: domain, application, and infrastructure with ports and adapters. A folder names a concept, never a mechanism such as Utils, Helpers or Managers.
  3. File, folder and type names follow the convention of the language of the file (table below). A file named after one type carries that type's exact name.
  4. A sum type and its variants stay in one file. Variants are not split into separate files.
  5. A use case lives in a folder named after its feature, in the ubiquitous language the feature builds with DDD, BDD and ATDD, readable by a person who is not an engineer.
  6. The layout does not change the paradigm: data is immutable, the methods of a type are pure functions, and effects stay in adapters.
  7. Test files follow the same convention. Which tests may reach a type directly is decided in nw-test-design-mandates, not here.
LanguageOne type per fileFolder or packageEvidence in tests/polyglot-pilot
Pythonsnake_case.py, named after its modulesnake_case packagesrc/codefact/python_ast.py
TypeScriptkebab-case.tskebab-case foldertypescript/src/app.ts, typescript/tests/common/state-delta.ts
Rustsnake_case.rs, one module per filesnake_case module folder with mod.rsrust/src/common/state_delta.rs
Gosnake_case.go, package named after its directorylowercase directory without separatorsgo/common/statedelta/state_delta.go
JavaTypeName.java, named exactly as its public typepackage directories, lowercasejava/src/test/java/common/StateDelta.java
C#TypeName.cs, named as its typedirectories matching the namespacecsharp/tests/Common/StateDelta.cs
KotlinTypeName.kt, named as its typepackage directories, lowercasekotlin/src/test/kotlin/common/StateDelta.kt
C++snake_case.hpp with snake_case.cpplowercase directorycpp/common/statedelta/state_delta.hpp

Comments, docs, closing statement

  1. Comments and docstrings give the reason for a choice or a dated incident; no "this module reads X", no numbers the code can derive.
  2. A document you change agrees with the code; fix the wrong side in the same change. Commands in a README or runbook run as written. Every nontrivial claim in a changed document is backed by a check the reader can rerun, or marked not measured.
  3. Call something wired or active only after running the surface that invokes it and seeing the effect.
  4. Closing statement: name the delivered behaviour, claim none the diff lacks. Show command and output for each check reported passed and for each numeric claim. Mark anything not run, stale or partly run as not measured, never as passed. Each unresolved finding names the obligation affected and a remedy.
  5. Report an independent pre-existing defect to its owner; fix it only when authorised or when it is a regression of this request. State in the closing statement every repair of a pre-existing defect and who authorised it.

Self-check before recording the step

  1. No fact decided twice; new owners justified.
  2. Every refusal says what, why, how, with located facts; remedy executed.
  3. Untrusted input validated, paths confined, races atomic.
  4. Recovery and failure-point tests or stated limits present.
  5. Each added check has a failing-on-violation assertion.
  6. Closing statement: commands with output, unknowns listed, pre-existing repairs named.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall