The feature was real. An agent that runs a multi-step workflow end to end, no human in the loop, proper retry handling. The engineer who built it was proud of it and had every reason to be.
Then a VP of Ops in the room asked one question. "Okay, so what does this replace on my team's plate on a Tuesday?"
Nobody answered. We had built the entire walkthrough around what the thing does instead of around her Tuesday.
Why this happens to engineers specifically
When you build something, you know it by its mechanism. You spent three weeks on the executor, so the executor is the interesting part. Parallel dispatch is interesting. The retry policy is interesting.
None of that is interesting to the person deciding whether to pay for it, and more importantly, none of it is interesting to the person who has to live with it.
The gap isn't a marketing problem that gets handed off later. It shows up in everything you write before marketing ever sees it.
Where it leaks into your own work
Changelog entries.
Before: Added support for multi-step agent execution with configurable retry policies.
After: Your agent can now finish a nine-step workflow without you watching it. If step four fails, it retries three times, then tells you which step broke instead of dying silently.
README opening line.
Before: A lightweight orchestration layer for autonomous agents.
After: Run agents that do the work while you sleep. You get a log of what they touched and a flag when they need you.
PR descriptions.
Before: Refactored the executor to support parallel task dispatch.
After: Workflows with independent steps now finish in about a third of the time. A ten-step run that took 90 seconds takes 30.
The second version in each pair contains the same information. It just leads with the consequence instead of the mechanism.
The test
Can someone who has never heard of AI agents read what you wrote and finish this sentence?
"This means I no longer have to ___"
If they can't, you've described a feature. Features are fine. They belong in the docs, under a header, where someone who already understands the problem goes looking for the mechanism.
But the first line of your README, the first slide of your demo, and the first sentence of your changelog are not for that person. They're for someone who has a Tuesday problem and no idea yet that you solve it.
What I'm still bad at
Writing feature-first copy is faster. It's also more flattering, because the mechanism is the part you're proud of.
I catch myself doing it constantly. The fix isn't a better instinct, it's running the test before I publish rather than after someone asks me the Tuesday question in a room full of people.
What's the last piece of AI or developer tooling copy you read that actually passed?
Top comments (0)