- Nov 4, 2026
- 3 min read
From Brainstorm to PIO to a One-Shot Agent Build
The git history of this project tells the story better than I can:
6386cfb prep pio tg bot scaffold + brainstorm readme
0f3d55f feat: tg inbound funnel v0.1.0 pio.md + bot + tests + docs, in one commit
e0075eb feat: add Makefile and Docker Compose deployment
bfcdc7f docs: note homelab SQLite bind-mount permissions
9ea8395 tg inbound bot ready
Step 1: brainstorm in chat
The first readme came from a chat session. It listed four integrations, each with a why:
- Telegram Bot API: the interface layer (read, approve, delete, ban).
- TypeSafe Jev: the “System 1” layer, a fast non-autoregressive classifier at a fraction of LLM cost.
- A small database: the memory layer.
- A human fallback: inline buttons for the grey zone.
It was useful for thinking, but too loose to build from. It even suggested classifying join requests with AI, which the final spec dropped.
Step 2: the PIO
It became a Problem – Integrations – Outcome doc with two extra sections:
## Problem why this hurts (manual review, spam, off-topic noise)
## Integrations Telegram, Jev, persistent store, owner review, RSS
## Version 0.1.0 behavior six numbered, testable rules
## Outcomes no routine join work; ≥99% spam mitigation (a target, not a claim)
## Operational assumptions one process, one group, one reviewer, text only
The numbered behavior section did the most work. Each rule is concrete enough to become a test:
- Count each message deleted through this moderation workflow once per user. On the second confirmed deletion, add a permanent database ban and ban the user in Telegram.
became test_second_distinct_deletion_bans_once. Rule 6 (“when the state store is unavailable, pause
processing until decisions can be recorded”) became the main loop’s error handling.
The outcome line deserves a mention. “99% of spam” is easy to write and hard to prove, so the PIO says explicitly that it’s a target to validate with real group data, not an initial performance claim. The agent carried that wording into the readme and the code comments instead of inventing an accuracy number.
Step 3: one pass
The PIO, community_bot.py, 12 offline tests, the CHANGELOG, a live-check list (tbc.md) and a learnings file
all landed in the same commit. The agent built from the spec, wrote tests against fake Telegram and Jev clients,
then I ran the live checks one at a time and ticked them off.
What I’d do differently
The scaffold files (status.json, roadmap.yaml, decisions.ndjson) were copied from a template and never
updated: status.json described an invoice project blocked on Stripe credentials. With no ADRs, every
design choice (long polling, standard library only, two strikes, owner exemption) was hidden in the readme.
A week later, on the next project, I added an adr/ folder halfway through and it paid off right away. So I went
back and wrote ADR-001 for this bot after the fact. The lesson: a PIO says what to build,
ADRs say why it’s built this way. You need both, and the template files must be filled in or deleted.
Next in this series: System-1 Moderation: Five Yes/No Questions and Two Thresholds
Part 1 of 6. Start with the series overview.