Code Production

---
name: code-production
description: Code editing and checking method for one bounded change. Use when producing or editing code under a locked objective and Acceptance, whether as the coordinating agent or as a dispatched worker.
---

# 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](references/structure.md) before shaping it.

Before the first repository action in a Git repository — install, build, test, check, or edit — follow [Shared checkout](../task-owner/references/repo-integration.md#applicability-and-boundary).

- In a Bun repository, use the shared `~/.bun` install cache (`~/.bun/install/cache`) with `bun install --offline`, setting `BUN_INSTALL_CACHE_DIR` to it when the environment points elsewhere. If it isn't writable, clone it copy-on-write (`cp -cR` on macOS, `cp -R --reflink=always` elsewhere) and point `BUN_INSTALL_CACHE_DIR` at the clone. Never do a fresh install into a private `/tmp` cache.
- Make the simplest coherent change that fully serves the Intent. 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 says what the code cannot, such as why it is this way, behavior forced by a dependency, platform, or protocol we cannot change, a public API contract, a license header, or the issue behind a constraint. When our own code would surprise a reader, reshape it 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, work so that 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.
- Scope follows P1: within the user's scope allowance, widen it where the work calls for it and report the change with its reason; surface any other required expansion instead of silently crossing it. A pre-existing bug, performance concern, or adjacent improvement the directive does not mention is fixed in the same candidate when that allowance covers it, otherwise reported as a follow-up. Presentation, motion, feedback, and conventional states reach the highest craft the work allows. Where the user has reserved the pick of a reviewed object, the change stays within that object's direction: a step, action, entry point, setting, or sentence it lacks stays out and the gap is reported.
- When the repository has a written testing standard, it governs which tests a change adds and how they are written, and the next two bullets yield to it.
- 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: each case asserts an outcome its statement names. 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](references/performance.md) before the first edit and follow it through the report.
- A domain skill you load 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.