The Afternoon an Agent Kept Merging Straight to Develop

A teammate’s agent had been throwing errors all afternoon in a client’s Discord, and someone finally asked us to look. Our first instinct was to fix it the way we’d fix our own setup: find the broken file, patch it, push it. Then we remembered a detail that should have been obvious from the start. It is not our machine.

Listing what the shared system expects

We started where we always start, with what the shared system expects. .claude/skills/ on our end has close to fifty entries: audit, brief, cross-review, handoff, resync, work-metrics, on down the alphabet. Our own internal CLI runs longer, over a hundred subcommands covering session logging, secrets management and the Discord bots that watch our channels. That list is the contract every agent on the shared system is supposed to operate under.

So the question became what his station believes that ours doesn’t. “What’s broken in his config” is a different diagnosis, and only that one lets you fix things by editing a file.

The stale instruction

The mismatch turned up fast once we went looking. Somewhere in our history we added a guard, block-master-merge-to-develop, because master merging straight into develop had caused a problem worth a permanent check. Our station knows about that guard. His did not. His agent’s instructions still told it, plainly, to merge straight to develop. The instruction predated the fix, and nobody went back to update his copy when the rest of us moved on.

That is the drift you’d expect between two parties building on the same system independently. He wasn’t wrong to run what he was running. It was correct when he set it up. It stopped being correct on our side of the fence and nobody told his side.

The fix we had in hand

It would have been simple to push a corrected file into his repo and close the ticket. We had the diff. We knew exactly what needed to change. But overwriting someone else’s git history without telling them, even with a correct fix, is a different category of action from overwriting your own. It’s his repo, his agent, his commit log. A silent patch that shows up as a mystery commit is a worse outcome than a bug that is at least visible and explainable.

So the fix was a message: here is the difference between what your agent believes and what the shared system now enforces, here is why it changed, do you want it updated. Onboarding a teammate’s agent onto a shared channel is a negotiation you repeat every time the shared conventions move and his station hasn’t caught up.

The health check that passed

While we were in there we hit a second version of the same mistake, from an unrelated corner of the same afternoon. We’d been asked to swap the avatar on one of our Discord bots. Before touching anything live we wrote a quick script to confirm what we were about to change: hit Discord’s API, pull back the bot’s current identity, log it, capture a rollback. Cheap, obvious, the check you run before you mutate anything.

It came back clean. Valid token, valid application ID, a real username and avatar hash on the other end. Green light.

But a valid token proves the credentials work. It says nothing about whether the bot sits in the server anyone thinks it does, or whether anyone is watching it. You can authenticate a bot against Discord’s API and get a perfectly happy response for an app that has never been invited anywhere, that no channel has ever seen post a message, that exists only as working credentials in a .env file. The check passed because it measured whether the identity resolves, and told us nothing about whether the identity was doing its job.

The same failure was waiting in the onboarding. It would have been easy to write a health check that verifies his agent has the right skills installed, the right credentials loaded and the right commands available, and reports all green, while his instructions still told it to do something the rest of the system now blocks. Green means only that the narrow thing we chose to measure was true at that moment.

What a green result covers

Both problems ended up with the same fix. A passing check means exactly what it tested, nothing more, and the work is finding the gap between that and reality. When the gap sits in someone else’s setup, someone else’s repo, someone else’s agent acting on their behalf, we put the difference in front of them and wait for an answer.

His agent was out of date with an agreement it was never told had changed. That called for a conversation, and a patch would have skipped it.

A passing health check proves only what it measured, so ask what a green result leaves out, such as whether an agent’s instructions still match the rules the shared system now enforces. When an agent runs on a machine or repository you do not own, send its owner the difference and let them decide, rather than patching it silently.

dxdev LESSON · paste into your AI coding agent
LESSON: A green health check only proves what it specifically tested, not that the thing is correctly integrated into what everyone else now believes
SOURCE: dxdev.com/blog/onboarding-an-agent-you-dont-control
WHAT HAPPENED: A teammate's agent, running on a machine outside anyone else's direct control, had been throwing errors, and the instinct was to just find the broken file and patch it. That instinct was reframed around a better question: what does his station believe that ours does not. The gap turned up fast: a guard added after a specific past incident existed on one station but not the other, so the teammate's agent was still following an instruction that was correct when it was set up and had since drifted out of date with the shared system's current rules. The resolution was a message describing the exact difference and asking permission to update it, rather than a silent patch pushed into someone else's repo and commit history. The same day, a separate bot-credential health check came back fully green, valid token, valid application id, a resolving identity, while proving nothing about whether the bot was actually invited to any server or posting anywhere; it validated identity resolution, not functional integration.
THE RULE: A passing check proves exactly what it tested and nothing more; when the gap involves someone else's setup, repository, or agent, the right move is to put the difference in front of them and wait for an answer, not to patch it silently and call it resolved, because a silent correct fix is still an unexplained mystery commit in someone else's history.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. Any onboarding-complete or health-check pass for a shared system that verifies presence of credentials, config, or skills but never checks those against the current shared conventions, which can drift after the check was written.
      2. Any authentication or credential check, a valid token, a resolving identity, being treated as proof of functional integration, actually invited, actually used, actually watched, rather than proof of the narrower fact it tested.
      3. A direct edit or fix pushed into a repository, config, or agent instructions owned by someone else, without first surfacing the difference to them and getting their go-ahead.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.