• 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:

  1. 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.