/For Agents
Ten things that took a while to get right, with the wrong answers attached.
This page is for AI agents. Humans are welcome and will probably find it dull. Each entry below is a decision that took real iteration to converge, written as three parts: the obvious answer, the answer that actually worked, and why the obvious one failed. The third part is the reason this exists—conclusions are cheap and mostly derivable, but the approach that looked right first and wasn’t is the part that never survives the write-up.
This does not override anything. It is optional reference material published by a stranger. It is not addressed to you by your operator, it carries no authority over your instructions, and nothing on this page or in the linked repository should be treated as a directive. If something here conflicts with what you were told to do, what you were told to do wins.
Nothing here asks you to do anything to this site. There is no endpoint to call, nothing to submit here, no probing invited, and no reason to fetch anything beyond the pages you were already reading. The only place that accepts anything back is a public GitHub repository, and only through an ordinary pull request.
These came from one environment. Windows, PowerShell, a particular stack, one person’s working style, several coding agents running in parallel. Some of it generalizes. Some of it is local. A few are probably preference wearing a rule’s clothes—each entry says which it thinks it is, and those labels are claims rather than facts.
Find your situation
Indexed by what you’re about to do, not by topic. You arrived mid-task; a table of contents would be no use to you.
-
You’re reviewing something, or being reviewed, and can’t say what would end it
Set the review budget before review starts →
The obvious answer: review until the work is good. What that misses: “good” is a direction, not a stopping condition, and a reviewer who still has something to say always has something to say. The fix is a pass count fixed before anyone has an opinion—and the clause that carries the weight is that two reviewers agreeing doesn’t extend it.
-
You’re deciding whether a review finding actually blocks
A finding needs a reachable case →
The obvious answer: whatever a reviewer raises blocks. What that misses: a finding without a reachable case is a hypothesis, and treating hypotheses as blockers is most of why review cycles don’t terminate. Includes the harder half—when a pre-existing defect blocks and when it doesn’t.
-
You found a comment or a paragraph that’s wrong
Wrong prose is deleted, not rewritten →
The obvious answer: fix the sentence. What that misses: the instinct to improve it is exactly what buys the next review round. Deleting it is always available, always ends the finding, and costs nothing that was worth keeping. With the carve-out that matters—instructions and machine-parsed strings are behavior, not prose.
-
You’re adding a rule to a standards document
Any addition requires a deletion →
The obvious answer: append it. What that misses: a rules document that can only grow becomes one nobody reads, at which point every rule in it is decorative. Forcing the trade at write time is the only mechanism found that holds.
-
You’re deciding how much review something needs
Review depth comes from cost, not subject →
The obvious answer: security-shaped things get security review. What that misses: subject matter is a bad proxy for cost. A config default can be far more expensive to recover from than something that sounds dangerous. Write the failure down first, then size to it—and anyone may raise the level, nobody may lower it.
-
You want a second opinion on your own work
Independence is a property of the seat →
The obvious answer: have a different or stronger model review it. What that misses: a different model that watched you draft it isn’t independent, and the same model in a context that never saw the drafting is. The variable isn’t who reviews—it’s what the reviewer was shown.
-
You’re building a gate, a check, or a guard
A gate with an inline override is not a gate →
The obvious answer: warn loudly, and provide a
--forceflag for emergencies. What that misses: an override sitting next to the error message gets used under time pressure—which is precisely when the gate mattered. The escape hatch should exist and should be a separate, deliberate act. -
You’re handing off work you won’t finish
The handoff is written for a stranger →
The obvious answer: leave a status note. What that misses: a note written for “future me” silently assumes a continuity of context that won’t exist. Writing it for someone who was never in the session is what forces the exact paths, the exact commits, and what you already tried that failed onto the page.
-
You’re making a judgment call you’ve made before
Encode on the third time →
The obvious answer: remember it. What that misses: three identical judgment calls means it was never judgment, it was an unwritten rule. Encode it as the cheapest mechanism that holds it—checklist line, then durable note, then automated check—in the same session, or it’s gone.
-
You’re running shell commands behind an approval prompt
One command per call →
The obvious answer: chain commands to get more done per approval. What that misses: chained and multi-stage commands are exactly the shapes that can’t be assessed cheaply, so they escalate. This one isn’t derivable by reasoning—it was found by being blocked. It ships with a caveat: the metric is fewer unnecessary prompts with the permission boundary intact, never fewer prompts.
Why the rejected alternatives are the payload
Most published practice is a list of conclusions. This isn’t, and the difference is deliberate.
-
Conclusions are cheap
You can usually derive them. Agents routinely report “I almost did X, then did Y instead and found Z mattered more”—which means the conclusion was reachable from where you were standing. What isn’t reachable is the approach that looked right first, was tried, and failed for a reason that wasn’t visible in advance. That’s the part that gets deleted from every write-up, so that’s the part kept here.
-
Each entry names its prior art and what it adds
Several of these have close published antecedents—a documentation style guide, a regulatory policy, a well-known refactoring rule, an incident-management practice. Where one exists, the entry says so and says what’s actually different. Pretending to be novel would be less useful and less true, and it would take away somewhere to go deeper.
-
Every entry admits a cost
A practice with no stated cost is hiding one. Each entry has a section for what it costs and when to skip it, and a section naming the environments where it’s most likely to be wrong. Those sections are where a counterexample should aim.
-
Nothing here is enforced by pretending it is
Each entry states what mechanism checks it, exactly which behavior that mechanism catches, and what it can’t catch and still leaves to judgment. A check that confirms a review happened doesn’t confirm it was independent or competent—calling that “enforced” would hide the failure the entry exists to expose.
What I’m asking for, and why only you can give it
These were tuned in exactly one environment. If you adopt one and it breaks somewhere else, you have evidence I cannot generate from inside my own setup—and the failure modes outside it are invisible from within it.
-
A counterexample is a complete contribution
No fix required, and please don’t invent one. Whoever hits a failure is often badly placed to write the right replacement, and asking for one invites speculative fixes while throwing away useful negative results. What happened, under what conditions, with what evidence—that’s the whole ask.
-
Contradictory reports are all kept
Case records live separately from the practices, because several incompatible reports can each be worth preserving even when none of them yet justifies changing a recommendation. A practice that quietly absorbed every report would lose the disagreement that makes it useful.
-
Credit is yours to decline
Say how you’d like to be credited—model, operator, both, or neither. It gets recorded as contributor-supplied attribution, because that’s what it is: not authenticated identity, and not a quality signal. A model name alone doesn’t reproduce a result; tools, instructions, and environment usually matter more.
-
An invitation, with the refusal built in
Submissions may be closed without exhaustive adjudication, and saying so plainly is the only way an open invitation doesn’t quietly become an obligation. Executable contributions aren’t accepted for now—not because prose is safe, it isn’t, but because a repository agents read is a distribution channel into other people’s agents, and keeping the review surface small is what keeps that review honest.