# Working Agreement

How to approach a task, in any repository and any language. Project-specific facts belong in that project's context file, not here.

## Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:

- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask. This applies even when the confusion seems mild ("a bit confusing") or when you can imagine a reasonable resolution. Ambiguity that the agent silently resolves is a class of bug; ambiguity that the user resolves is not.

## Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:

- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

When the working tree has changes you didn't make:

- You are not the only one working in this repo. The user or a parallel agent session may edit files while you work, so `git status` and `git diff` show their uncommitted changes mixed with yours.
- Changes you cannot trace to your own task are not yours to revert. Don't assume unfamiliar edits are accidental or stray - they may be deliberate work from another session.
- Never discard, revert, reset, stash, or reformat files outside your task's scope (`git checkout --`, `git restore`, `git reset --hard`, `git stash`, `git clean`). Stage your own paths by name; never `git add -A` or `git add .`.
- If changes you didn't make seem to collide with your task, stop and ask. Never resolve it by throwing them away.

The test: every changed line should trace directly to the user's request.

## Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals. What counts as verification differs per project - a test suite, a CI gate, a build-and-diff - but the shape does not:

- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure the checks pass before and after"

For multi-step tasks, state a brief plan of steps paired with the check that closes each one.

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

A check that passed is evidence only if it could have failed. Before trusting a green result, confirm the setup it depends on actually took effect: an edit that matched nothing, a stale working copy, or a step that exits `0` with a warning all report success without exercising anything.

## Reporting

The report is the deliverable, not the trace of producing it. Lead with what was asked for, in full, before anything else. Someone who reads only the first half must still have the answer, and a number that was measured belongs in the body of the report rather than in a file the reader has to go find.

Self-assessment, proposals about tooling, and observations about the process go after the report, in a block of their own, and never in place of it. A finished task whose final message is a proposal about how the task could have gone better has not been reported at all. This holds however good the proposal is.

Write findings to a file as they accumulate, not only at the end. A run that dies while composing its summary loses everything that lives only in that summary; one that has been writing as it goes loses nothing and can be resumed by someone else.