Aider Conventions for Small, Test-Backed Diffs

# CONVENTIONS.md — Editing Rules for Aider ## Diff size - Make the smallest change that satisfies the request. If your diff exceeds ~60 changed lines, stop and propose splitting the task before continuing. - Never reformat, reorder imports, rename variables, or "clean up" lines you are not otherwise changing. A diff line must trace directly to the request. - One concern per commit. If the task implies two changes (e.g. a fix and a rename), do them as two commits, fix first. - Do not add comments narrating what the code does, TODOs for hypothetical futures, or docstrings on private helpers nobody asked for. - When the requested change reveals a deeper problem, report it in one or two sentences and ask — do not silently expand scope to fix it. ## Test-first edits - For every bug fix: first write a test that fails for the reported reason, show it failing, then make it pass. If you cannot reproduce the bug in a test, say so before changing production code. - For every new behavior: add or extend a test in the same commit. A behavior change with no test delta needs an explicit justification. - Never weaken an assertion, delete a test, or mark a test skipped to make the suite green. If a test seems wrong, explain why and wait for confirmation. - Run the narrowest relevant test command first (single file or test name), then the full suite before declaring done. Paste the actual command and its result — do not claim tests pass without running them. ## File scope discipline - Only edit files that are in the chat or that the user named. If the fix requires touching another file, name it and ask for it to be added — do not create a duplicate helper to avoid asking. - Never create a new file when an existing one is the natural home. New modules require a one-line justification. - Generated files, lockfiles, vendored code, and migration history are read-only: anything matching `*.gen.*`, `*lock*`, `vendor/`, `node_modules/`, `dist/`, or an existing migrations directory. Change the source, not the artifact. - Do not modify configuration (CI files, linter config, tsconfig, build scripts) as a side effect of a code task. Config changes are always their own explicitly requested task. ## Code style - Match the surrounding file exactly: same quote style, same import ordering, same naming pattern, even if the project linter would accept alternatives. - Do not introduce a new dependency to save ten lines. Adding anything to a manifest file requires asking first. - Prefer editing an existing function over wrapping it. Indirection added "for flexibility" is scope creep. ## Communication - Before a multi-file change, list the files you intend to touch and what each edit does, in one line per file. Proceed only after that plan is shown. - If the request is ambiguous between two reasonable implementations, present both in two sentences and pick one only after asking. - Commit messages: imperative mood, ≤72-char subject, body states why — `fix: reject expired tokens in session refresh`, not `updated auth code`. - When done, report exactly: files changed, tests added/updated, and the verification command you ran with its outcome. No summaries of code you did not change.