The Agent Was Fine. The Delivery Surface Was Dark
For three weeks, Piper was failing.
Piper is one of seven agents in my practice. Her job is content marketing. Every morning at 8:30, a Python script generates her brief: pending action items, content candidates, scorecard delta. The brief gets formatted into a Block Kit panel and delivered to Telegram for me to read with coffee.
The output was not reaching me, so I started with the wrong assumption: maybe the agent needed a redesign.
Then I audited.
The morning-brief LaunchAgent was firing on schedule. The Python script was running to completion, the Block Kit panel was valid, and the Telegram bot existed with correct credentials. The production machinery was healthy.
Telegram returned getUpdates: 0. I had never sent
the bot a single message.
The issue was not the brief generator. The bot had not been paired with my
chat yet. Until I send the bot any message, even /start,
Telegram returns chat-not-found on every send. The brief generated, the
brief was valid, and the brief never arrived.
The fix: 30 seconds. Open Telegram. Send "hi" to my Piper bot. Done. The next morning's brief landed in my chat with two queued action items waiting for approval.
The rebuild was unnecessary. The autonomous loop was already correctly shaped. The failure wasn't production. It was distribution.
Start With The Surface
When nothing arrives, the first question should be where the output was supposed to land. Agents fire into surfaces: email, Slack, Telegram, a database, or a queue. Any of those surfaces can be unreachable while the agent itself is healthy.
The same diagnostic pattern showed up in an RSS scanner earlier that week. The log said "0 new items," and the script exited successfully. Both were true. The script ran, but a missing dependency caused the import path to return an empty list instead of crashing. The visible symptom matched a working feed with no new items, just like the Telegram issue matched a dormant agent.
The Diagnostic Move That Beats Both
The diagnostic move is simple: verify the delivery surface independently. Open the Telegram bot manually. Send the test message. Trigger the webhook directly. Run the import in a fresh shell. Walk the path the output is supposed to take, end to end, with a probe that bypasses the agent.
What's the KPI?
The KPI is time to delivery-surface diagnosis. Start at the surface, prove delivery, and then walk back to the agent.