damn you, agents

i ask an agent to change something small. it comes back with a function long enough to have its own table of contents.

the feature works. somehow, that makes this more annoying. now i have to explain why working isn't the only thing i asked for.

i got back into coding because the idea of AGI made me want to help build something. i still want that. i would just prefer not to spend the next five years reviewing infrastructure for a button.

this is the bar i want to hold these changes to. no magic prompt, and no rule that every function has to be five lines. just a way to decide whether the code is earning its place.

start with the actual change

before reading the implementation, i want one sentence describing what should happen. something concrete enough that i can try it myself.

for example: when the contact field contains a message, the send button should turn blue. when it's empty or disabled, it should stay gray.

that sentence gives the review a boundary. i can check the empty state, type a message, clear it, and check what happens while the form is busy. it also gives me a reason to question a new theme manager. which part of this sentence required one?

a vague task gives every extra piece of code somewhere to hide. "improve the form" could mean almost anything. "make this state visible" gives me something to accept or reject.

follow one ordinary case

i want to be able to follow a normal interaction from beginning to end. a person types. the value changes. the button becomes available. they send their message.

if following that path means opening six files, i want to know what those files are separating. sometimes there is a good answer. shared validation might belong somewhere else. a component used by several pages might deserve its own file.

but moving three lines into another file doesn't automatically make them easier to understand. it can just make me click more.

the useful question is whether the structure helps me explain the behavior. if i can explain the old code in a sentence and need a diagram for the replacement, the replacement has some explaining to do.

question the extras

i'm suspicious of code written for a future version of the task. an option nobody passes. a setting with one possible value. a generic handler with exactly one caller.

any of these can become useful. i want the reason to be present in the change i'm reviewing, though. otherwise i'm maintaining a prediction.

this is a better follow-up prompt than simply asking the agent to make everything shorter:

List the new helpers, options, and state in this change. For each one, name the current behavior that requires it. Remove anything justified only by a hypothetical future use. Preserve the behavior and the existing checks.

shorter code can still be awful. compressing a readable function into one expression might reduce the line count while making every future edit worse. i want fewer things to keep in my head, not a better score at code golf.

try deleting it

pick an extra piece and ask what stops working without it. be specific. which input, which page, which interaction?

if the answer is "nothing right now," that's useful information. delete it and run the relevant checks. if the answer names a real behavior, keep that behavior and see whether the implementation can be more direct.

this is also why i don't want an agent rewriting neighboring code while it's here. each unrelated change gives me another thing to understand before i can answer the original question.

test the promise

a test should tell me when something i care about breaks. it shouldn't merely confirm that the agent arranged the code the way it arranged the code.

take the slash shortcut on this site. pressing / outside the contact field should focus it. pressing / while writing a message should type a slash. a modifier-key shortcut should keep doing whatever the browser uses it for.

those are separate promises worth checking. a test that only confirms a keydown listener exists tells me almost nothing about whether any of them work.

the same goes for appearance. a passing build won't tell me that a portrait's ear gets cut off on hover. i still have to look at it. preferably before declaring that everything is done.

i want the checks to match the risk of the change. a missing piece of punctuation doesn't need an elaborate test suite. a rule that blocks a pull request from merging probably does.

leave less behind

the agent can finish generating a change long before i'm finished understanding it. accepting the output transfers that problem to me.

so before i keep it, i want to know what it does, why the extra pieces exist, and how i'd notice if it broke. i also want the comments and docs to describe the version that actually survived the review.

sometimes the answer really is a longer function. sometimes five lines would lose an important case. that's fine. i can live with code that has a reason to be there.

i'm less interested in maintaining 395 lines of enthusiasm.