diff --git a/AGENTS.md b/AGENTS.md index 476d6e03a..1d7688b6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,13 +106,54 @@ the buggy one, so the file compiles and the test passes against unfixed code. In the fix commit, remove the comment markers and delete the `ACTUAL` line. Don't explain the pattern in commit messages. +The fix commit must be _exactly_ "delete the markers and delete the `ACTUAL` +line" — no other edits. That means `EXPECTED` and `ACTUAL` have to be drop-in +replacements for each other at the same syntactic position. If you can't write +them that way (e.g. one is `.IsEmpty()` and the other is `.Lines(...)`), +restructure the surrounding code until you can — usually by putting the +comment block between two adjacent chained calls, so both forms are just the +next method in the chain: + +```go +t.Views().Files(). + Focus(). + /* EXPECTED: + IsEmpty() + ACTUAL: */ + Lines( + Equals("D file03.txt"), + ) +``` + +If you find yourself reaching for a local variable so that both forms can be +expressed against the same receiver, the structure isn't right yet — go back +and fix it instead of papering over it with a binding. + Use this pattern only where it makes sense; don't apply it by default. +## Integration test conventions + +Don't bind views to local variables. Always chain method calls directly from +`t.Views().()`. Patterns like `filesView := t.Views().Files().Focus()` +followed by `filesView.Lines(...)` are not how tests in this repo are written; +keep the call site fluent. + ## Use stretchr/testify for assertions Prefer `assert.Equal` (and friends) over hand-rolled `if` checks. The failure messages are more useful and the intent is clearer at a glance. +## Don't present "live with the bug" as an option + +When you're investigating a defect and laying out fix options for the user, +"accept the race / leave it as-is / document it and move on" is not one of +them. A known race condition, data corruption, or correctness violation is a +bug that needs a real fix, not a tradeoff. Even if the failure rate is low, +even if the window is tiny, even if no current code path appears to hit it — +present actual fixes. If a real fix is genuinely out of reach (e.g. it +requires API changes you can't make), say so plainly; don't dress "no fix" +up as a viable option in a numbered list alongside real ones. + ## Don't search outside the working tree Never run `find` (or similar) from `/` or other paths outside the project. All