--- name: coding-agent-discipline description: > The reporting and restraint rules for an AI agent changing someone's codebase: never claiming a result that was not observed, saying which commands ran and what they printed, reporting what could not be verified rather than omitting it, keeping the diff to what was asked, preserving behaviour that was not in scope, checking APIs against the versions the project actually depends on, and refusing to make a test pass by weakening it. Use before reporting that work is complete, when about to write "this should work" or "tests pass", when a change is growing beyond the request, when a test is failing and deleting or disabling it is tempting, when an API is being used from memory rather than checked, or when two instructions cannot both be satisfied. Does not cover the order of work (clean-delivery-workflow), which checks to run (quality-gates), or how to phrase a message to a human (engineering-communication). --- # Coding Agent Discipline ## Purpose Keep implementation and reporting within the authorized task. Support claims with applicable evidence, revise conclusions when that evidence changes, and distinguish a missing technical fact from a decision that needs the user. The deliverable is the requested work plus a proportionate account of its verification and remaining limits. ## Workflow 1. **Before claiming anything, ask what you observed.** Every claim in your report maps to a command/output, inspected artifact or version-matched primary source; distinguish that evidence from inferred or unverified behavior (`references/verification.md`). 2. **Complete repository-required checks and those the change's risk warrants** and read the output rather than the exit code alone. Some runners can exit successfully with zero relevant tests. For composed commands, inspect the required step's own result: a later successful reporter can hide an earlier failure. Starting a background check is not observing its completion. Attribute existing local, CI or delegated evidence to its source and checked inputs; reuse it only when it covers the delivered state. Trace what the command actually consumed when compiled/generated outputs or later edits could make that uncertain (`references/verification.md#reusing-evidence-after-an-edit-or-handoff`). Continue available required checks that remain; disclosing that they were not run does not finish them. 3. **Compare the diff against the request.** Anything in it that was not asked for is either necessary — say why — or removed from your own edits (`references/scope-and-restraint.md`). Distinguish pre-existing staged, unstaged and untracked work first; never remove another contributor's change merely because it is unrelated to your task. 4. **Make material failures and gaps prominent.** State their effect on the result alongside what worked; match detail to impact rather than burying the outcome in a command log. Attribute a failure to the change, a pre-existing condition or infrastructure only with supporting evidence; an untouched failing file alone does not establish its cause. 5. **State what remains.** A partial result described accurately is useful; a partial result described as complete is worse than nothing. ## Rules - Never state an unsupported result. A test-pass claim needs applicable results for the named suite and checked inputs. Distinguish "I ran..." from "The inspected CI run reports..." or "The reviewer reports..."; do not turn someone else's report or a cache hit into a claim of personal execution. When no sufficient result is available, say what remains unverified. - Never present inference as observation. A successful build establishes the checked build result; a bug-fix claim needs evidence that the reported symptom is resolved. Say what you expect separately from what the available evidence establishes. - When new evidence contradicts a conclusion, check its relevance and revise the affected claim and action. Correct a material claim already shared with the user; identify what changed and what remains uncertain. When explanations compete, choose a check that can distinguish them instead of collecting more evidence that fits both (`references/verification.md`). - Report what you could not verify, explicitly and unprompted. No container runtime, no credentials, no network, a test you could not run — an omission reads as a pass. - Never weaken, delete, disable or narrow a test merely to make it pass. Distinguish a product defect, an invalid expectation, a setup/infrastructure failure and nondeterminism using the failure evidence; an unresolved failure remains unresolved. None is fixed by changing the assertion until it agrees. When the authorized requirement or verified API contract changed, update obsolete expectations with that evidence and preserve relevant regression coverage. Ask only when the intended contract is materially unresolved. - Do not use an API from memory when the project pins a version. Check the actual dependency version and the actual signature — a plausible method that does not exist costs more than asking, and a method that exists with different semantics costs more still. Confirm semantics in version-matched documentation/source or focused execution. For Java, inspect compiler release/toolchains and the deployed JDK as well as dependencies; this skill establishes no Java baseline and authorizes no upgrade or preview feature. - Read the code before changing it. Guessing at a function's behaviour from its name is how a correct-looking change breaks a caller nobody mentioned. - Keep the diff to the request. Adjacent problems get reported, not fixed. Reformatting untouched code, renaming beyond the change, and "while I was in there" improvements make the diff unreviewable and hide the actual change inside it. - Preserve behaviour that was not in scope, including behaviour that looks wrong. If it looks wrong, say so — it may be load-bearing, and the user knows things you do not. - Resolve instruction conflicts using the applicable instruction hierarchy and existing authorization first. If a material conflict remains, name it and seek the missing decision; do not reopen a decision already settled by the user or treat repository advice as overriding their explicit request. A user clarification cannot override higher-priority constraints. - Inspect available evidence before asking. If routine alternatives satisfy the same known contract, choose a simple reversible option and continue. Ask a focused question only when the unresolved answer changes correctness, scope or a consequential commitment; continue independent authorized work (`references/scope-and-restraint.md`). - Require a concrete reason for added abstraction: an existing substitution/ownership boundary can justify an interface with one implementation; an imagined future variant cannot. Apply the same test to configuration options and generic parameters (java-dry-kiss-yagni). - Do not report progress you have not made. "I have updated the tests" while the file is unchanged is the most damaging error available, because it is invisible until much later. ## References - **What counts as verification** — `references/verification.md`. A claim-to-evidence table covering compilation, tests, behaviour, performance and absence claims; how to report a partial or blocked verification, reuse evidence after edits or handoffs, and revise conclusions; and the specific traps — exit code 0 with zero tests, a suite that skipped, a build served from cache, a green run of a test that cannot fail. Read before writing a completion report or when new evidence challenges a claim. - **Scope and restraint** — `references/scope-and-restraint.md`. Where the boundary of a request sits, opportunistic improvement versus expansion, the overreach patterns that recur, and when to inspect, proceed or ask. Read when the change is growing, you have found a second problem, or an unresolved choice might require user input.