code-production

Code production

Before the first edit, decide whether the change adds or reshapes a type, a module, stored data, or a command or job that writes files or records. If it does, read references/structure.md now; it sets how that new shape is built.

• Make the smallest coherent change that satisfies Acceptance. Modify or delete before adding; remove the superseded path in the same candidate. Prefer targeted edits when they keep the change easy to review; a broader rewrite is appropriate when it produces a simpler reviewable result without absorbing unrelated or concurrent work. The proportion of lines changed does not decide the method.
• In the code you change, a comment carries only what the code cannot say: a license header, behavior forced by a dependency, platform, or protocol we cannot change, a public API contract, or a link to the issue behind a constraint. When our own code needs a comment to explain surprising behavior, reshape the code by renaming, extracting, or typing until it explains itself. A comment that guards a constraint ("do not remove", "keep this wording") stays until a test or check enforces that constraint; when that enforcement is outside owned scope, report it as a follow-up. A lint suppression stays only for a style-only rule; one that silences a correctness or safety rule is resolved in the code.
• Before handing over, read your own diff once as its reviewer and remove what it added without need: comments that narrate the code, defensive checks or try/catch on trusted internal paths, casts that bypass the type checker, and nesting an early return would flatten.
• In a sweep, migration, or batch of similar edits, check each unit before starting the next, so a break shows at the unit that caused it. For such a batch, or a check you will repeat across many units, reuse an existing rerunnable command or script when one covers the work, otherwise write the smallest script that does or proves it, and keep the invocation as a receipt a reviewer can rerun; a couple of edits visible at a glance need none.
• Stay inside owned scope. Surface a required scope expansion instead of silently crossing it. A pre-existing bug, performance concern, or behavior the directive does not mention stays untouched unless Acceptance cannot be met without it; report it as a follow-up. A step, action, entry point, setting, or sentence absent from the approved review object stays out and the gap is reported; within the object's direction, presentation, motion, feedback, and conventional states reach the highest craft the work allows.
• A new test needs an expected outcome from outside the code it checks; a test written from the same reading as the implementation repeats that reading. Three sources supply one. A bug: the fix starts with a case that fails on the unfixed code for the reported reason. A decided requirement that predates the change: the cases are written from its statement by an agent other than the producer, before it sees the candidate change, and arrive in the directive or from a verifier; without such cases the producer adds no requirement test. This independent-author part is on trial. A trust boundary (authentication, money, deletion, privacy, or a guard on production or secrets): independently derived adversarial cases stay required. Every other change adds no test and runs the existing checks that cover it.
• Test behavior through the public interface, at the seams the directive or Intent names. A test that restates the implementation is a defect, not coverage: one that copies a value the code already holds (a count or roster from a registry, copy text, prompt wording, a constant, source or script text), asserts only that a mock was called, or recomputes the expectation the way the implementation does. A check over every entry of a registry enumerates the registry. When an intended change breaks a restating test, delete or rewrite it rather than update its copy. When a module deepens behind a new interface, delete the superseded shallow tests in the same change. Size committed tests like the neighboring test files, roughly one focused test per stated behavior; scratch checks used during verification need not be kept. A committed test runs production code or checks a formal structure such as a schema, path, heading, link, or size; a one-time observation, such as a deleted file being absent, belongs in the result's evidence.
• Run the smallest checks that directly judge the changed predicates. Broaden to regression or build coverage when the actual impact surface or dependency uncertainty requires it, and repeat or broaden passing checks only when new changes, failures, or unresolved concerns justify it. Record exact command, exit or result, and raw output location when available. Silence, timeout, malformed output, or a skipped check is not a pass.
• For a performance change, where speed, latency, memory, size, frame rate, or cost is the target, read references/performance.md before the first edit and follow it through the report.
• Load a domain skill only when the artifact needs that specialist procedure. The skill does not widen scope or change Acceptance.
• A wait you own — a probe still scanning, a check or deploy still running, a process you started — belongs to this change: stay with it until it reaches terminal state or its stated bound, then report.