DEV Community: Ryo Suwito

Yo Vibe Coders, Stop Building FE Slop and Use Telegram Groups Instead

Ryo Suwito — Sat, 30 May 2026 04:49:40 +0000

We know. We KNOW. AI has been slopping you React frontends faster than you can say npm install. Tailwind components, shadcn copy-paste, v0 screenshots, the whole pipeline. Bro your "frontend" is just vibes and dependencies at this point 😮‍💨

But real talk — do you actually need a web interface, or do you just need something to interact with your backend?

Sit down. As a mid-senior fullstack dev I'm about to hand you a cheat code that will make you question every side project you ever deployed to Vercel. Grab a pen and paper fella because I'm only saying this once.

Your frontend is a Telegram group.

No seriously. Put the laptop down. Let that marinate.

The Stack (No Brainer Edition)

Here it is. The whole thing:

FastAPI — your backend. clean, fast, you already know it.
SQLite — your database. one file. on your disk. done.
ngrok — exposes your localhost to the world. free tier exists.
Telegram Bot — your entire frontend, UX, notification system, and auth layer.

Infra cost? Your potato PC and ngrok. That's it. Cope that your electricity doesn't go out randomly.

If you're feeling fancy, slap it on a $5 VPS and you're running a production-grade hobby setup. Whatever. Point is there's no AWS bill coming at the end of the month to ruin your weekend.

No Docker compose files with 9 services. No CI/CD pipeline. No node_modules folder eating 400MB of your SSD. No "deployment failed" notification at 2am.

Just:

uvicorn main:app --reload
ngrok http 8000

and you're live. genuinely.

Groups Are Pages, Actually

Here's the mindset shift that breaks your brain in a good way.

Every Telegram group your bot is invited to = one page of your app.

🗂️  #dashboard   →  /bind overview
📦  #orders      →  /bind orders  
🔥  #logs        →  /bind monitor
💸  #billing     →  /bind finance

How does the bot know which "page" it's on? chat_id. That's it. Every group has a unique chat_id. Your bot receives a message, checks the chat_id, looks up which service is bound to it, and routes accordingly.

You just built URL routing with zero code. Telegram handed it to you.

And look what you get for FREE on top of that:

Auth — Telegram users ARE their accounts. no JWT, no OAuth, no "forgot password" flow. they exist, they're in the group, they're authed.
Push notifications — just sendMessage to the group. that's a notification.
File handling — images, PDFs, CSVs. upload, download, just works.
Buttons — inline keyboards. no CSS. no click handlers. no state management. just a list of strings with callbacks.
Mobile + Desktop — Telegram runs everywhere. your "responsive design" is Telegram's problem now.
Audit log — the chat history IS your activity log. everything your bot ever posted, timestamped, searchable. for free.
Collaboration — multi-user? just invite them to the group. that's your RBAC.

You didn't build any of this. It was just there.

One Bot, Many Microservices (The Accidental Architecture)

Okay now it gets unhinged.

You can take this further. Same bot instance, different groups, each group bound to a completely different microservice.

Telegram
   │
   ├── group #A  (chat_id: 111) ──►  Service A  :8001
   ├── group #B  (chat_id: 222) ──►  Service B  :8002
   └── group #C  (chat_id: 333) ──►  Service C  :8003

         bot = your API gateway

Your bot is literally just a router. It doesn't know what the services do. It just translates Telegram events into HTTP calls and Telegram messages back. Each service is dumb — it just returns "what to say." Clean separation. No service knows about Telegram at all.

And here's the kicker: your services are independently everything. Independent SQLite. Independent FastAPI instance. Independent deployment. You want to update the billing service? You restart :8002. The rest of your "app" doesn't flinch.

People pay real money for infra that does this — service discovery, routing, isolation. You got it by thinking about group chats differently. Congrats on your accidental microservices architecture. Put it on your CV.

Clear Chat = Refresh Page

This one is my favorite.

You know how sometimes your UI just feels cluttered? Too much state on screen, too many old messages, overwhelming?

You're an admin. Just clear the chat history.

Zero consequences. The bot doesn't care. FastAPI doesn't care. SQLite DEFINITELY doesn't care. The actual state of your app lives in your database. The chat is just the render buffer. Wipe it whenever.

It's like having a terminal you can clear without killing the process.

Compare this to a real frontend where "resetting UI state" is a whole ticket. localStorage cleanup, cache busting, Redux resets, "why is stale data still showing up." Two days of your life gone.

Or you could just... clear chat. as admin. in 2 taps.

Go Build Something

Look. This is for your hobby projects. To save you from Vercel bills, from npm hell, from building a whole React app for a thing your wife, neighbor, and dog are the only users of.

Share the groups with whoever needs access. That's your user management. That's your multi-tenant solution. You need more than that? Hire a proper team then. Okay? Good.

Now close this tab and go /bind something.

FastAPI + SQLite + ngrok + one Telegram bot. That's the stack. Touch grass after shipping.

AI Labs wild dream

Ryo Suwito — Wed, 20 May 2026 11:52:53 +0000

Karen: "I need to track my dog grooming appointments and send reminder texts"
AI (enthusiastically): "I'll build you an appointment system!" [generates 800 lines of React, a Node backend, SQLite schema, API routes]
Karen: "Okay... now what?"
AI: "Just run npm install then npm run dev and open localhost:3000!"
Karen: "What the fuck is npm"
AI: "It's Node Package Manager! Here's how to install Node.js..." [sends markdown documentation]
Karen: [googles "salesforce alternatives"]

see? we devs ain't that doomed

Your Code is a Sacred Cow Bred by a Slop Machine. Put Your Business Logic in Postgres.

Ryo Suwito — Mon, 18 May 2026 21:25:42 +0000

"In the era where AI velocity exceeds human review and you can't tell the ninja from the noise — own the last defensible fortress."

The Lie We've Been Telling Ourselves

Every best practice in modern software engineering is a social contract pretending to be an engineering solution.

Code review. PR checklists. Linting pipelines. Clean architecture. SOLID principles. Testing pyramids. These work beautifully in a fantasy team — small, senior-heavy, stable, everyone reads the architecture docs, everyone cares.

That team doesn't exist at scale. It never really did.

And in 2025, it's completely, irreversibly dead.

AI Just Nuked the Last Pretense

The old control loop was: slow down output → review → gate → merge.

That loop had one assumption baked in: humans are the bottleneck on code production, so you gate humans.

That assumption is gone. The code is now infinite and free. Your junior dev with Cursor ships 10x what your senior shipped in 2019. Your contractor uses Claude Sonnet and delivers a feature in a day that used to take a sprint. Your intern doesn't even write code — they write prompts and review diffs they barely understand.

And here's the part nobody's saying out loud:

The tests are AI-generated too. They test what the AI thought it was building.

The PR looks immaculate. Consistent style. Well-documented. Green CI. And the business rule is subtly, quietly wrong — because the agent didn't know about the edge case your senior learned from an incident three years ago that never made it into a spec.

You can't add enough reviewers. You can't make the checklist long enough. You cannot out-review the velocity.

The Sacred Cow That Breeds From Slop

Here's the current reality of "business logic in application code":

Your rules live in service classes, middleware, serializers, validators — spread across layers, replicated across services, enforced by convention and prayer.

Every new dev who joins — bootcamp grad, offshore contractor, AI-assisted intern — touches that code. Every PR is a potential bypass. Every "quick fix" is a load-bearing card in a house of cards.

And now the code itself is generated by a machine that has no memory of why the rule exists, no context for the incident that created it, and no skin in the game if it gets it wrong.

You have perfect version control over slop. Git tells you exactly which commit introduced the wrong behavior. Congratulations. The audit trail of your own mistakes is immaculate.

Meanwhile, you're doing standup, sprint planning, architecture reviews, and PR approvals — all of it cope. Elaborate institutional cope to manage the entropy of logic that was never safe outside a controlled environment.

The Churn Math Nobody Wants to Do

Ask yourself honestly: which role churns faster at your company?

The JavaScript developer — framework-hopping, chasing the ecosystem, mentally rewriting their stack every 18 months. React → hooks → RSC. REST → GraphQL → tRPC. Webpack → Vite → whatever drops next Tuesday. Their knowledge doesn't compound. It rotates.

Or the bearded guy with the SQL wand.

The senior DBA who's been writing joins since before your current frontend framework was a GitHub repo. Whose CTEs from 2015 still run. Whose understanding of indexes, vacuuming, and query planning compounds year over year. Postgres 17 still respects everything he wrote in Postgres 10.

You also cannot fake SQL mastery in an interview. Run EXPLAIN ANALYZE on the query. No leetcode theater. No rehearsed system design answers. Either the query plan shows 3ms with an index-only scan, or it shows a sequential scan on 2 million rows and you're done. The database is the interviewer, and it has no unconscious bias and cannot be charmed.

Meanwhile your JS interview pipeline is a gymnasium for people who memorized 50 leetcode patterns for 3 weeks. They pass. They join. You find out 6 months later.

Own What AI Cannot Slop

Here's the reframe:

There are now two zones in your system.

Above the line: AI territory. Generate freely. Redeploy in minutes. Let the contractors, the juniors, the agents write it. Move fast. Break things. The BFF, the frontend, the API adapters — disposable by design. This is where velocity lives and chaos is acceptable.

Below the line: The fortress. Slow. Deliberate. Council-gated. Changes are rare and ritualistic. This is where correctness lives and velocity is the enemy.

The line is the database boundary.

And the crucial insight: you cannot prompt your way into changing a trigger. The AI can generate a million BFF variations. Every single one hits the same wall. The invariant holds not because anyone checked the PR, but because the system enforces it at a layer where velocity doesn't operate.

What the Postgres Temple Actually Looks Like

The PostgreSQL-centric architecture — sometimes called Planetary Architecture — inverts the conventional stack:

Raw tables are locked. REVOKE ALL from everyone including the application user. Superadmin only.
Views are the only access surface. One table, many views — scoped by role, redacted by sensitivity, filtered by RLS policies.
INSTEAD OF triggers are the only mutation path. Business logic lives in Postgres functions called by triggers. Not in your service layer.
Row-Level Security is authorization. Not middleware. Not JWT decoded in a controller. The database itself decides what each role can see and touch.
FDW forensic audit writes to a separate database server on a separate host. Append-only. If your main DB gets ransomwared, the audit trail is untouched.

The application user — the one your PostgREST or Django connects with — can see metadata on raw tables but never read a row directly. The BFF consumes views and calls functions. It has no idea what the underlying schema looks like.

A junior dev, an AI agent, an offshore contractor — they work on the BFF. They literally cannot bypass business logic because there is no surface to touch. The database rejects it at the query level.

The Seniors Become Force Multipliers

This architecture changes what "senior" means.

In a conventional stack, seniors spend their leverage on reviews, mentoring, and trying to slow down the entropy of a dozen people touching business logic simultaneously. They're playing defense constantly.

In the Postgres temple, the senior writes the fortress once, correctly. Encodes the rules into trigger functions, RLS policies, view contracts. Then steps back.

The chaos above the line doesn't require their supervision anymore — because the architecture does the supervision. One council of SQL wardens can safely oversee an arbitrarily large BFF team of agents, juniors, and contractors. The blast radius of any mistake above the line is hard-bounded by what PostgREST exposes, which is bounded by what views exist, which is bounded by what the senior built.

The more junior and AI-heavy your above-the-line becomes, the more valuable the below-the-line fortress gets. The chaos above justifies the rigidity below.

This Isn't a 90s Idea. It's the Correct Response to 2026

The Oracle shops of the 90s had this right. Business logic in stored procedures. Schema changes as rituals. DBAs as priests. Nobody pushed to production without the warden's blessing.

We abandoned it because startups needed to move faster than that culture allowed, and Rails made it feel unnecessary. We traded correctness guarantees for velocity, and it worked — when humans were still the velocity bottleneck.

That trade no longer makes sense. The velocity problem is solved. The correctness problem is now existential.

The bearded SQL warden who stays 10 years, whose fortress gets stronger over time, whose knowledge doesn't deprecate — that person is now the most strategically valuable engineer in your organization.

Not because SQL is magic. Because owning the one layer that AI cannot slop is now the entire game.

The One Sentence

Your code is a sacred cow bred by a slop machine, kept alive by PR prayers and best-practice inhalers.

Put your sacred cow in Postgres, where the DB is the priest, and no agent, no junior, no tired tech lead reviewing his 40th PR of the week can accidentally sacrifice it on a Friday deploy.

The fortress holds. The orbit burns. That's the architecture.

Inspired by PostgreSQL centric - Planetary Architecture by Ryo Suwito.

Tags: #postgres #architecture #systemdesign #webdev #programming

PostgreSQL centric - Planetary Architecture

Ryo Suwito — Mon, 18 May 2026 12:39:32 +0000

Product Requirements Document

PostgreSQL is not the persistence layer. It is the application. Everything else is orbit.

1. Vision

Modern web stacks treat the database as a dumb filing cabinet at the end of a long chain — request → router → controller → service → ORM → DB. Business logic is smeared across every layer. Security is enforced in the app. Permissions live in middleware. Mutations go through serializers. The database just executes INSERT and stays quiet.

Planetary Architecture inverts this.

PostgreSQL is the sun. Every other component — the admin dashboard, the HTTP adapter, the frontend, the external services — orbits it. Business logic, authorization, validation, transformation, and auditing all live inside Postgres. Downstream layers are deliberately dumb: they render, they route, they receive webhooks. They do not own logic.

The platform — django-pg-planetary — is the control plane that makes this architecture operable without writing a single line of SQL. It extends Django admin into a full database operations dashboard, serving every persona involved in building and running a Planetary stack.

2. The Stack

┌─────────────────────────────────────────────────────────────┐
│                      CONTROL PLANE                          │
│         django-pg-planetary (Django Admin Extension)        │
│         Karen · Bob · Senior Dev — one unified dashboard    │
└──────────────────────────┬──────────────────────────────────┘
                           │  DDL only · metadata only
                           │  never raw table data
┌──────────────────────────▼──────────────────────────────────┐
│                   ☀️  POSTGRESQL (the app)                   │
│                                                             │
│  raw tables      — superadmin only, REVOKE ALL on everyone  │
│  views           — DTOs, redacted, role-scoped              │
│  INSTEAD OF      — the only way CUD ever happens            │
│  functions       — business logic, overloaded by signature  │
│  RLS policies    — authorization at the row level           │
│  triggers        — mutations, audits, notifications         │
│  types/domains   — validated, reusable data shapes          │
│  FDW             — forensic audit to separate DB            │
│  pg_notify       — async event emission                     │
└────────┬────────────────────────────────────────────────────┘
         │                              │
         │ pg_notify / pg_net           │ SQL over HTTP
         │                  ┌───────────▼──────────┐
         │                  │       PostgREST       │
         │                  │   dumb HTTP adapter   │
         │                  │   exposes views +     │
         │                  │   functions as REST   │
         │                  └───────────┬──────────┘
         │                              │ REST + JWT
         │                  ┌───────────▼──────────┐
         │                  │     Next.js BFF       │
         │                  │  renders · consumes   │
         │                  │  zero business logic  │
         │                  └───────────┬──────────┘
         │                              │
┌────────▼──────────────────────────────▼──────────────────────┐
│                   SERVICES (dumb, isolated)                   │
│     pdf-export · email · payment · sms · storage · etc.      │
│     receive payload · do one thing · return result           │
│     know nothing about the DB schema                         │
└──────────────────────────────────────────────────────────────┘
         │
┌────────▼──────────────────────────────────────────────────────┐
│                    AUDIT DB (FDW shadow)                       │
│     separate server · append-only · forensic isolation        │
│     full before/after JSON trail per row per operation        │
└────────────────────────────────────────────────────────────────┘

3. Personas

Karen — Business Operations

Uses Django admin to browse and manage data rows. Her experience is unchanged from standard Django admin. She interacts with views only — never raw tables. RLS ensures she sees exactly what her role allows, automatically.

Bob — DevOps / DB Administrator

Uses the planetary extension to manage the full Postgres security and infrastructure layer. Zero SQL written. He manages roles, grants, policies, table health, scheduled jobs, replication, and configuration through GUI forms that generate and execute SQL behind the scenes.

Senior Developer

Uses the extension to design and apply the Postgres application layer. Writes function bodies, designs view schemas, declares protected tables, manages types, configures FTS, and controls the audit setup. The platform scaffolds everything; Senior fills in the business logic.

PostgREST (system actor)

Watches Postgres. Exposes whatever views and functions exist as REST endpoints, scoped by JWT role claims. Picks up every change Senior makes automatically. No configuration required per new view or function.

Next.js BFF (system actor)

Consumes PostgREST endpoints. Renders data. Calls service endpoints for non-DB operations. Has no knowledge of the underlying schema, RLS rules, or function signatures.

4. Core Principles

4.1 The Protected Table Contract

Every raw table in a Planetary stack follows this contract:

REVOKE ALL ON raw_table FROM PUBLIC — no one touches data directly
REVOKE ALL ON raw_table FROM app_role — includes the Django DB user
One or more views declared as the only access points
INSTEAD OF triggers on each view — the only mutation path
Overloaded functions per operation type — validation and transformation
RLS on views — row-level authorization per role/claim

The platform scaffolds steps 1–6 from a single "Protect this table" action. Senior fills in function bodies. Everything else is generated.

4.2 Views as DTOs

A view is not a convenience — it is an explicit API contract. One raw table can have many views:

invoice_raw          ← locked, superadmin only
  invoice_v          ← standard ops view, status + amounts
  invoice_v_finance  ← finance role, full breakdown
  invoice_v_redacted ← public-facing, PII masked
  invoice_v_audit    ← compliance, all fields + metadata

PostgREST exposes each view as a separate endpoint. RLS on each view enforces who can query what. No app-layer serializers needed.

4.3 Metadata ≠ Data Privileges

Revoking data access from the Django DB user does NOT revoke metadata access. The platform can fully introspect any table's columns, types, constraints, indexes, policies, and triggers via pg_catalog and information_schema — without ever reading a row of actual data. This is the foundation of the view builder, policy editor, and trigger scaffolder.

4.4 Functions as the Business Logic Layer

Postgres functions are:

Overloadable by signature — process_invoice(a) and process_invoice(a, b) coexist
Transactional — they run inside the trigger's transaction
Testable — callable directly via PostgREST or SELECT
Replaceable — CREATE OR REPLACE with no downtime

All validation, transformation, computed fields, and side-effect orchestration live in functions. The app layer calls views. It never implements business logic.

4.5 FDW Forensic Audit

Audit triggers write to a foreign table backed by a separate database server via postgres_fdw. The audit DB is:

On a different host (optionally different provider)
Append-only by policy — no UPDATE, no DELETE
Invisible to application roles
Full row_to_json(OLD) / row_to_json(NEW) per operation

If the main DB is compromised, wiped, or ransomwared — the audit trail is untouched on a completely separate server. The platform wires this up per table with a toggle.

5. Platform Features

5.1 Introspection Engine

The foundation. Pure pg_catalog + information_schema queries. Returns structured metadata the UI builds on. No data access required.

Tables, columns, data types, nullability, defaults
Constraints — PK, FK, unique, check, exclusion
Indexes — type, columns, partial condition, expression
Views + materialized views — definition, dependencies
Stored functions + procedures — signature, language, body, security
Triggers — timing, event, level, condition, function
Policies — command, roles, USING, WITH CHECK expressions
Roles + grants — membership, table/column/schema privileges
Extensions — installed, available, version
FDW servers + foreign tables
Publications + subscriptions
Table health — live tuples, dead tuples, bloat, last vacuum/analyze

5.2 Protected Table Manager (Senior + Bob)

The core workflow of the platform.

Declare a table as protected:

Select table from introspected list
Platform generates REVOKE statements for all non-superadmin roles
Column picker: drag-drop columns into one or more named views
Per-column: include / exclude / apply redaction function
Platform generates CREATE VIEW for each declared view
INSTEAD OF trigger skeleton auto-generated per view
Senior writes function body in inline editor
One-click apply — REVOKE + views + triggers executed in single transaction

View builder:

Visual column selector from introspected schema
Redaction function picker (mask_pan, mask_email, hash, nullify, etc.)
Live SQL preview
Role assignment — which PostgREST role sees this view
RLS policy generator — column picker for USING expression

5.3 Policy Manager — RLS / RBAC / ABAC / PBAC (Bob + Senior)

RLS Policies:

Enable/disable RLS per table/view — toggle
Create policy: name, table, command (ALL/SELECT/INSERT/UPDATE/DELETE)
USING expression builder — column picker + operator + value/function
WITH CHECK expression builder
PERMISSIVE vs RESTRICTIVE toggle
Role assignment
Live SQL preview
Active policies list with enable/disable per policy

Role Management (RBAC):

Create / rename / drop roles
Role membership — assign roles to roles (hierarchy)
Grant / revoke table privileges per role
Grant / revoke column-level privileges
Grant / revoke schema privileges
Grant / revoke function execute privileges
Role matrix view — roles × tables × privileges grid

Session Claims (ABAC):

Define current_setting('app.x') claim variables used in policies
JWT claim → set_config mapping documentation per role
Policy expression helpers using claim variables

Policy Templates (PBAC):

User-owns-row: user_id = current_setting('app.user_id')::uuid
Tenant isolation: tenant_id = (auth.jwt() ->> 'tenant_id')::uuid
Soft-delete filter: deleted_at IS NULL
Time-bounded: valid_from <= now() AND valid_to >= now()
Save custom templates — reusable across tables

5.4 Function & Trigger Manager (Senior)

Functions:

List all stored functions with signature, language, security mode
Create / edit function — inline code editor with syntax highlighting
Language picker — plpgsql, sql, python (plpython3u)
SECURITY INVOKER vs SECURITY DEFINER toggle
Parameter builder — name, type, default, mode (IN/OUT/INOUT)
Return type picker — scalar, setof, table, trigger, void
Function overload group view — all signatures for same name
Test runner — call function with sample args, see output

Triggers:

List all triggers per table with status
Create trigger: timing (BEFORE/AFTER/INSTEAD OF), event (INSERT/UPDATE/DELETE/TRUNCATE)
Column-specific UPDATE trigger (OF col1, col2)
FOR EACH ROW vs FOR EACH STATEMENT toggle
WHEN condition builder
Function picker from existing trigger functions
Enable / disable per trigger
Deferrable + deferred toggle

Event Triggers (DDL-level):

Fire on CREATE TABLE, ALTER TABLE, DROP, etc.
Auto-attach audit triggers to any new table — set-and-forget for Bob
Enforce naming conventions on DDL operations

5.5 Schema Object Manager (Senior + Bob)

Views:

List all views with definition preview
Create / edit view — column picker + SQL editor
Dependency graph — which tables/functions a view uses
Drop cascade safety — shows what breaks before executing

Materialized Views:

Create materialized view from view or raw SQL
Refresh strategy — manual / pg_cron scheduled
Refresh schedule builder (cron expression)
Index management on materialized view columns
Concurrent refresh toggle

Custom Types:

ENUM types — create, add values, rename, drop
Composite types — field builder with name + type
Domain types — base type + CHECK constraint
Range types — subtype + canonical function

Extensions:

Available extensions list with description
Install / drop per extension
Version display
Commonly useful: uuid-ossp, pgcrypto, pg_stat_statements, pg_cron, pg_net, postgres_fdw, postgis, unaccent, btree_gin

Sequences:

List, create, alter (start, increment, min, max, cycle)
Current value display
Owned-by column display

Schemas:

Create / drop schemas
search_path configuration per role
Move tables between schemas

5.6 Index Manager (Bob + Senior)

List all indexes — type, columns, size, usage stats
Detect unused indexes via pg_stat_user_indexes (idx_scan = 0)
Create index — type picker (B-tree, GIN, GiST, BRIN, Hash)
Partial index — WHERE clause builder
Expression index — expression input with column picker
Concurrent build toggle (non-blocking)
Index size vs query benefit display

5.7 Full Text Search (Senior)

Text search configuration manager
Dictionary management
tsvector column setup — which columns, which config
to_tsvector expression builder
GIN index auto-suggestion on tsvector columns
Test query — enter search terms, preview ranked results

5.8 Audit Layer (Bob)

Enable audit per table — toggle
FDW server configuration — host, dbname, credentials
Foreign table auto-creation on audit DB
Audit trigger auto-generated and attached
Audit log viewer (reads from foreign table — read-only)
Audit DB health status
Retention policy — pg_cron job to prune old audit records (on audit DB side)

5.9 Replication & CDC (Bob)

Publications — create, add/remove tables, manage row filters
Subscriptions — create, monitor lag, enable/disable
Logical replication slot monitoring
FDW connections — list, test, drop

5.10 Scheduled Jobs — pg_cron (Bob)

List all cron jobs with schedule, last run, status
Create job — SQL input + cron expression builder
Enable / disable per job
Run now (immediate one-off execution)
Job run history + error log

5.11 Notifications — pg_notify / pg_net (Senior)

NOTIFY channels in use — list active LISTEN connections
pg_net webhook trigger builder — target URL, payload template
Outbound webhook log (via net._http_response)

5.12 Performance & Health (Bob)

Table stats — live tuples, dead tuples, bloat %, last vacuum/analyze
pg_stat_statements — top queries by total time, calls, mean time
Cache hit ratio — buffer hits vs disk reads
Connection stats — active, idle, idle-in-transaction, by role
Lock monitor — active locks, blocking queries, wait graph
VACUUM / ANALYZE — trigger manually per table or ALL
Autovacuum settings — per-table overrides (fillfactor, thresholds)
Table size breakdown — table + indexes + toast

5.13 Configuration (Bob)

ALTER SYSTEM GUI — categorized parameter list
Search params by name or description
Current vs pending (requires reload) indicator
pg_reload_conf() trigger button
Per-database and per-role parameter overrides via ALTER DATABASE SET / ALTER ROLE SET

5.14 PostgREST Integration

View → PostgREST endpoint mapping display
Function → RPC endpoint display (/rpc/function_name)
JWT role claim → Postgres role mapping documentation
Schema cache reload trigger (NOTIFY pgrst, 'reload schema')
Endpoint health check per view

6. Non-Goals

Not a data browser. Django admin owns rows and data management. This platform does not display table contents except for the audit log viewer.
Not a query editor. Not a replacement for psql, DBeaver, or TablePlus. Senior who needs raw SQL uses those tools.
Not an ORM. No model abstraction. Everything is native Postgres SQL, generated and executed directly.
Not a migration framework. No Alembic/django-migrate style versioned migrations. DDL changes are applied directly. Event triggers handle DDL auditing.
Not a connection pooler. PgBouncer / Supavisor are separate infrastructure concerns.

7. Privilege Architecture

superadmin         → everything. raw tables, DDL, pg_catalog, config
senior_dev role    → DDL via platform, metadata, no raw table data
bob_devops role    → platform UI operations, metadata, health stats
django_app role    → metadata on raw tables, data on views only
postgrest role     → data on views, scoped by JWT sub-role
karen role         → rows in views, filtered by RLS
audit_writer role  → INSERT only on foreign audit tables

The platform authenticates as django_app for introspection. DDL operations are executed via a separate platform_ddl role with elevated privileges, scoped to specific operations, never exposed to the HTTP layer.

8. Package Design

django-pg-planetary/
├── planetary/
│   ├── apps.py                  ← PlanetaryConfig, auto-registers admin
│   ├── introspect/
│   │   ├── tables.py            ← columns, types, constraints
│   │   ├── policies.py          ← pg_policies queries
│   │   ├── roles.py             ← pg_roles, memberships, grants
│   │   ├── routines.py          ← functions, triggers, event triggers
│   │   ├── objects.py           ← views, matviews, types, sequences
│   │   ├── indexes.py           ← index stats, usage
│   │   ├── health.py            ← pg_stat_*, vacuum, bloat
│   │   └── replication.py       ← publications, subscriptions, slots
│   ├── builders/
│   │   ├── policy_builder.py    ← CREATE/ALTER/DROP POLICY → SQL
│   │   ├── role_builder.py      ← GRANT/REVOKE/CREATE ROLE → SQL
│   │   ├── trigger_builder.py   ← CREATE/DROP TRIGGER → SQL
│   │   ├── view_builder.py      ← CREATE VIEW / INSTEAD OF → SQL
│   │   ├── function_builder.py  ← CREATE OR REPLACE FUNCTION → SQL
│   │   └── audit_builder.py     ← FDW setup, audit trigger → SQL
│   ├── executor.py              ← safe DDL execution, transaction wrapper
│   ├── admin/
│   │   ├── policy_admin.py
│   │   ├── role_admin.py
│   │   ├── schema_admin.py
│   │   ├── trigger_admin.py
│   │   ├── function_admin.py
│   │   ├── health_admin.py
│   │   ├── audit_admin.py
│   │   └── cron_admin.py
│   ├── templates/
│   │   └── admin/planetary/     ← per-view HTML templates
│   └── static/
│       └── planetary/           ← JS for live SQL preview, editors
└── setup.py

Installation:

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'planetary',               # adds Planetary section to admin
    ...
]

PLANETARY = {
    'DDL_ROLE': 'platform_ddl',          # elevated role for DDL ops
    'AUDIT_SERVER': 'audit_db_server',   # FDW server name for audit
    'POSTGREST_URL': 'http://localhost:3000',
}

9. The Paradigm in One Sentence

Karen checks the data. Bob secures the database. Senior encodes the rules. Postgres enforces everything. PostgREST exposes it. Next.js renders it. Services handle the side effects. Nobody writes middleware.

Stop Treating Agentic AI Like a Deity (Or Like a Dumb Intern)

Ryo Suwito — Thu, 14 May 2026 06:39:53 +0000

There's a better way — and it starts with sequential derivation.

Happy to be here writing this on a day off. Sometimes the best thinking happens when you're not under pressure. This is one of those thoughts that's been sitting in the back of my head for a while, and I think it's worth sharing with anyone building real products with agentic AI right now.

The Two Camps

If you've been in developer spaces lately — Discord servers, Twitter threads, Reddit arguments — you've noticed that the dev community has split into two very vocal camps when it comes to agentic AI.

Camp One: The Deity Worshippers.
These are the devs who hand the AI a vague idea and expect a production-ready app. "Build me a SaaS." They treat the agent like an omniscient oracle. When it fails (and it will), they rage-quit and write a hot take about how AI is overhyped.

Camp Two: The Micromanagers.
These are the devs who've been burned before. They spoon-feed every line, double-check every output, and end up doing more work than if they'd just written the code themselves. The AI becomes a glorified autocomplete, and they wonder why they're paying $20/month for it.

Here's the thing: both camps are wrong. about the workflow.

The Problem Is the Handoff.

Every time I've seen agentic AI fail spectacularly, the root cause isn't the model. It's that the human didn't set the stage properly. We either gave it too much freedom with too little context, or we gave it so much rigid instruction that we killed its ability to be useful.

The real skill is sequencing.

Agentic AI is not a search engine you query once. It's a collaborator you build with — step by step, output feeding the next input, each artifact narrowing the possibility space for the next agent in the chain.

When I figured this out, my development velocity changed. Dramatically.

The Derivation Chain: How I Actually Build Now

Here's my workflow, distilled. I call it the Derivation Chain — every artifact you produce becomes the foundation for the next one. Nothing is created in a vacuum.

Phase 1 — The Foundation (Identity Layer)

It always starts with an idea and a name. But most of us stop there and jump straight to code. That's the mistake.

Instead, I let the name derive everything else:

Name
  └─► Vision & Mission
        └─► Core Values
              └─► Brand Guidelines + Copy Tone & Language
                    └─► Color Palette + Style Guide
                          └─► Component Guide
                                └─► Framework-Specific Best Practices

Every step is a sequential prompt to an agentic AI, and every output becomes the context document for the next step. The AI doesn't guess. It derives.

By the time I'm done with Phase 1, I have a living design system that's coherent from the name all the way down to the button radius. Not because I manually crafted it — because I sequentially derived it.

This is the part most devs skip. And it's the part that saves you the most time later.

Phase 2 — The Problem (Product Layer)

Once the foundation is set, I turn my idea into a Problem Statements file. Not a feature list. Not a backlog. A structured document that clearly articulates:

Who is suffering?
What are they suffering from?
Why do existing solutions fail them?
What would a meaningful resolution look like?

The agentic AI helps me write this, but I drive the content. The AI's job here is to help me think clearly, not to invent problems I don't have.

Phase 3 — The Architect (Solution Layer)

Here's where it gets interesting — and counterintuitive.

Once I have the Problem Statements, I bring in what I call the Unbiased Architect.

The rule is strict: the Architect sees zero existing code.

Why? Because existing code carries compounding mistakes. If your codebase started with a bad architectural decision six months ago, and you show it to an AI and ask "how do we build on this?" — you get solutions built on top of flawed foundations. The AI inherits your tech debt intellectually.

The Unbiased Architect reads only the Problem Statements. From there, it defines the ideal solution architecture: bounded contexts, data contracts, state machines, service boundaries — without being anchored to what you've already built.

The Architect's deliverables:

Problem Statements
  └─► Ideal Solution Architecture
        └─► Domain Models & Data Contracts
              └─► Service Boundaries & Bounded Contexts
                    └─► Agent Bill of Materials

Phase 4 — The Agent Bill of Materials

The last output from the Architect is what I call the Agent Bill of Materials (or Agent Bill Request): a document that defines:

How many agents are needed
The scope and responsibility of each agent
The handoff contracts between agents
The individual guide each agent should operate under

Think of it like a staffing plan — but for AI agents that will execute work in parallel, each with their own bounded domain and clear success criteria.

From this point, the execution phase begins. Each agent gets its own brief and works within its lane. The chaos of "just ask the AI" is replaced by structured, accountable parallel delivery.

Why This Works

The magic of this approach is that it solves three fundamental problems with agentic AI development:

1. Context Coherence
Every document feeds the next. By the time you're writing code, the AI has absorbed your brand, your values, your problem space, and your architecture. It's not guessing your intent — it's operating from a rich, layered context.

2. Architectural Integrity
By separating the Architect from the Builder, you prevent the AI from inheriting and amplifying your existing mistakes. The ideal solution exists independently of the messy reality of your current codebase.

3. Parallel Execution Without Chaos
The Agent Bill of Materials gives each agent a clear scope. Parallel execution becomes possible without agents stepping on each other's work, because boundaries are defined upfront.

The Mindset Shift

The real unlock is this:

You are the Director. The AI is the department.

You don't tell a department head every keystroke to make (micromanagement). You also don't hand them a napkin sketch and say "build the company" (deity worship).

You give them:

Clear context
A defined scope
Outputs from the previous phase as their input
Freedom to operate within those constraints

That's it. That's the workflow.

Practical Checklist

If you want to try this yourself, here's the order of operations:

[ ] Start with a name and idea
[ ] Derive: Vision & Mission → Core Values
[ ] Derive: Brand Guidelines → Copy Tone → Color Palette → Style Guide
[ ] Derive: Component Guide → Framework-Specific Best Practices
[ ] Write Problem Statements (AI-assisted, human-driven)
[ ] Engage the Unbiased Architect (no code access, problem-only context)
[ ] Generate the Agent Bill of Materials
[ ] Execute with scoped agents

Closing Thought

We're in a weird transitional moment. The tools are powerful enough to genuinely accelerate professional development — but most developers are either over-trusting them or under-utilizing them.

The devs who win in this environment won't be the ones who master prompt engineering. They'll be the ones who master workflow design — who understand that agentic AI is most powerful when it operates inside a well-designed sequential system, not as a standalone oracle.

Build the system. Let the AI fill it.

The best ideas don't always come during sprints. Sometimes clarity arrives when you step back.

If this resonated, drop a comment — I'm genuinely curious how others are structuring their agentic workflows.

Tags: agentic-ai devworkflow productivity aitools softwaredevelopment

🎬 "FREE MONEY, THEN WHAT?" A Timeline Nobody Told You About

Ryo Suwito — Mon, 04 May 2026 20:26:26 +0000

Not financial advice. Not doom content. Just... connecting dots.

📌 HOW TO READ THIS

This is a story about money, technology, human behavior, and a very old joke.
It starts with free pizza and ends with... well, you'll see.
Grab a snack. This one's worth your time.

🕰️ CHAPTER 1: THE FREE PIZZA ERA

(2010 – 2018)

Do you remember when Gojek was giving away free rides?

Or when GrabFood had promo codes that made your meal cost literally Rp0?
Or when a new e-commerce app would give you Rp200,000 cashback just for downloading it?

You probably thought: "Wow these companies are so generous."

Here's the thing. They weren't being generous.
They were spending investor money to buy your habit.

Here's how the game worked.

Somewhere in Silicon Valley — or Singapore, or Tokyo — giant pools of money called Venture Capital funds were sitting around, looking for the next big thing.

The pitch was simple:

"South East Asia has 600 million people. Most of them just got smartphones. Whoever owns their daily habits owns the future. Spend now. Profit later."

And the investors said: "Sure. Here's a billion dollars."

So Gojek burned cash. Tokopedia burned cash. Shopee burned cash.
Not because they were bad at business.
Because the strategy was to burn cash on purpose — to make you dependent on their app before you even realized it.

The free rides weren't free.
You were the product being built.

This era had a name in Silicon Valley: "Blitzscaling."
The idea: grow so fast, so everywhere, that by the time anyone else tries to compete, you already own the market.

It worked spectacularly.

By 2018, hundreds of millions of Southeast Asians had smartphones, digital wallets, and the habit of buying things with one tap.

The infrastructure was ready.

Now it was time to sell them something more profitable than pizza.

🕰️ CHAPTER 2: THE LOAN COMES FOR DINNER

(2016 – 2020)

Quick question.

If you had just spent years teaching hundreds of millions of people to trust an app with their money... what would be the most logical next product to offer them?

If you said a loan — congratulations, you think like a fintech CEO.

In 2016, Indonesia's financial regulator OJK officially recognized Fintech P2P Lending — what most people now call pinjol (pinjaman online / online loans).

The promise was beautiful:

"Millions of Indonesians have no access to banks. No credit history. No collateral. We will use technology to give them loans anyway — using their digital footprint as proof of trustworthiness."

Sounds like financial inclusion. Sounds like progress.

And for many people, it genuinely was.

A street vendor who couldn't get a bank loan could now borrow Rp2 million to buy more stock. A young worker could cover a medical emergency without selling their phone.

Real problems. Real solutions. Real people helped.

But there was another group of borrowers showing up too.

Meet the second group.

Young, urban, smartphone-glued.
Just spent three years being trained by apps to buy things instantly.
Now being shown an equally instant way to borrow money.

No branch visit. No salary slip required. No collateral.
KTP + selfie + a few taps = money in your e-wallet in 15 minutes.

The interest rate? Buried in the fine print.
0.3% per day. Which sounds small until you realize that's 109% per year.

But who reads fine print when you really want those concert tickets?

Buy Now, Pay Later arrived at the same time and made it even smoother.

No interest! (if you pay on time)
Four easy installments!
Available right there at checkout — between "Add to Cart" and "Order Confirmed."

The entire point was to remove the moment of hesitation between wanting something and buying it.

And it worked. Beautifully. Terrifyingly.

By 2020, the numbers were already staggering:

93% of Gen Z and Millennials in Indonesia used digital wallets
31% were using Paylater
10% had active pinjol loans

Most of them were borrowing for wants, not needs.
OJK's own data: 65% of pinjol money was spent on non-essential purchases.

Concerts. New phones. Fashion.
FOMO with a payment plan.

🕰️ CHAPTER 3: THE TRAP SNAPS SHUT

(2020 – 2023)

Here's a thing about debt that seems obvious but somehow isn't:

When the loan is easy to get, people forget it's still a loan.

When repayment is spread across tiny installments, the total cost becomes invisible.

When your friend also has four active pinjols and seems fine, it feels normal.

And when the app keeps offering you more credit because you paid last month's on time... you take it.

The psychological mechanism has a name: debt normalization.

It happened slowly, then all at once.

Gen Z, born into a world of digital everything, grew up watching social media show them lifestyles they couldn't afford.

FOMO — Fear Of Missing Out — became a legitimate financial force.
YOLO — You Only Live Once — became a spending philosophy.

"I'll just put it on paylater."
"Everyone does it."
"I'll pay it off when I get my next salary."

The salary came. Another bill was already waiting.

This is where the math starts to break.

Say you have three active paylater/pinjol accounts.
Each month you're paying installments on all three.
Your salary barely covers it — plus rent, food, transport.
So you borrow a little more next month.
To pay the previous month.

Financial experts call this the debt spiral.
The TikTok community later gave it a simpler name.

But we'll get to that.

By 2023, OJK's data showed:

Gen Z and Millennials (age 19–34) held 54% of all pinjol debt — Rp27 trillion
They were also the biggest source of bad debt (kredit macet)
Outstanding bad debt over 90 days hit Rp1.73 trillion in mid-2023 — up 55% from the year before

The official narrative: "These young people have low financial literacy."

True. But also:

They were actively targeted by apps
Marketed to through social media influencers
Given loans before they understood what compound interest meant
And the apps were specifically designed to make saying yes easier than saying no

Low literacy, or high predation?

Both, probably.

🕰️ CHAPTER 4: WHEN THE BORROWERS ORGANIZED

(2023 – 2025)

Here's the old joke:

"If you borrow Rp500,000 and can't pay — YOU have a problem."
"If a million people borrow Rp500,000 and can't pay — THE BANK has a problem."

Someone on TikTok figured this out.

Then they told their followers.
Who told their followers.
Who made memes.
Who made tutorial videos.
Who built communities.

Gerakan Galbay — literally "The Fail-to-Pay Movement" — emerged organically on social media around 2024-2025.

No founder. No manifesto. No political party.

Just millions of people independently arriving at the same conclusion:

"I cannot pay this anyway. And if enough of us don't pay — what exactly are they going to do?"

The content that spread fastest wasn't angry or radical.
It was practical.

TikTok videos titled:

"Daftar Pinjol Aman Galbay" (List of pinjols safe to default on)
"Cara Lepas dari Pinjol Tanpa Takut" (How to escape pinjol without fear)
With hashtags: #salamgalbay (galbay greetings)

Facebook groups like "Solusi Galbay Pinjol Legal & Ilegal" — 10,000+ members.

WhatsApp groups sharing intel: which platforms have no field debt collectors, which ones won't pursue legal action over small amounts, which ones will negotiate.

What was the nuclear threat supposed to be?

SLIK OJK. The credit scoring system.

The official warning:

"Galbay = bad credit score = can't get KPR, can't get car loan, can't get jobs that check credit history."

And for previous generations, that threat worked.
A ruined credit score meant a ruined financial life.

But for this generation?

KPR? First-time homebuyer age in Indonesia is already pushing 40. Dream deferred anyway.
Car loan? Grab exists.
Job that checks SLIK? The informal economy is 59% of the workforce.
Social shame? Hard to feel shame in a 10,000-member community that celebrates your decision.

The gun wasn't loaded.
Or more precisely — they called the bluff, and found out it wasn't loaded.

The industry panicked.

AFPI (the fintech lending association) filed reports with OJK.
They discussed it with the police.
They asked the Ministry of Communications to block the content.

Komisi XI of Parliament demanded OJK intervene.

OJK issued new regulations — raising the minimum borrower age, requiring minimum income of Rp3 million.

All of which were responses to a movement that had already happened.

Meanwhile, the numbers kept moving:

By June 2025, bad debt for borrowers under 19 years old had jumped 763% year-on-year.

21,774 active bad debt accounts in that age group. Up from 2,521 the year before.

A 763% increase.

In one year.

For people who weren't even legally adults when many of them took the loans.

🕰️ CHAPTER 5: THE SHELL GAME

(2024 – 2026)

Here's something the black-suit world doesn't advertise.

When a bank or pinjol platform has too many bad loans on its books, it has options beyond just writing them off.

Option 1: Restructure — give the borrower more time, lower installments. Kick the can.

Option 2: Sell the loan — find a debt buyer willing to purchase the bad loan portfolio for, say, 15 cents on the dollar. The bank takes a loss, but the problem is now someone else's problem.

This is completely legal. It happens everywhere. It has a whole industry built around it.

In Indonesia, the national asset management company PT PPA openly offers this as a service.
They literally advertise: "We assist banks in divesting loans that hinder their operational and financial performance."

And in mid-2024? BBRI, BTN, and KB Bank were simultaneously selling bad asset portfolios to manage their NPL numbers.

After all this, OJK announced: "NPL perbankan masih terjaga."

Bank NPL is still healthy.

Which was... technically true.
Because they moved the garbage off the balance sheet.

Here's the key metric to watch: TKB90.

Every pinjol platform in Indonesia is required to display it on their homepage.

TKB90 = the percentage of loans paid back within 90 days.

A platform showing TKB90 of 97% looks very healthy.

But here's what TKB90 doesn't show you:
What happened to the loans that weren't paid back?

Were they written off? Restructured? Or quietly sold to a third party before they could hit the 90-day mark?

If you sell a loan on day 85, it never enters the TKB90 calculation at all.

The metric measures what's left. Not what was removed.

This game works perfectly.

Until the third-party buyers stop buying.

Which happens when they also can't collect.

Because the borrowers — remembering the old joke — decided not to pay the debt collectors either.

The Galbay community had already crowd-sourced exactly this intelligence.
They knew which debt buyers had field collectors. Which ones didn't. Which ones would negotiate. Which ones would fold.

When the debt buyer's business model breaks...
The bank can no longer offload.
The bad loans stay on the balance sheet.
The real NPL finally appears.
And that number is not the "still healthy" number OJK was announcing.

🕰️ CHAPTER 6: THE CREDIT SCORE LOSES ITS TEETH

(2025 – 2026)

Here's a beautiful irony.

The SLIK OJK system — the supposed guardian of financial discipline — is being quietly dismantled from two directions at once.

Direction 1: Borrowers ignore it.

We already covered this. The Galbay community treats SLIK merah as a badge, not a punishment.

But here's the kicker:

The fintech platforms themselves created the workaround.

Since 2024, major pinjol apps openly market themselves as "no BI checking required."
They use AI to assess you based on:

Your GPS movement patterns
What smartphone you own
How often you shop on Tokopedia or Shopee
Whether you pay your electricity bill on time
The names in your phone contacts (yes, really)

Someone with a completely ruined SLIK score from a state bank default can get approved on ShopeePayLater in 2026 — because the system sees they're an active shopper who always tops up their Grab credits.

The industry built its own bypass lane around the official credit system.
Because it needed the volume. Because the volume is the business.

Direction 2: The sales floor goes blind.

Now here's the part nobody tells you.

The pool of "clean SLIK" young Indonesians is shrinking every month.
More Galbay defaults. More pinjol NPLs recording into SLIK. More young people with Kol-5 (worst rating) on their credit file.

Meanwhile: a car dealership salesperson's commission doesn't shrink along with the clean-SLIK pool.

Their rent is still due. Their kids still need school fees.
Their sales quota from head office? Unchanged.

So what do you do when the "normal" customers are gone?

You start reading the articles on AstraOtoshop.com titled:
"Kredit Motor Tanpa BI Checking 2026: 6 Leasing Solutions for Bad Credit Scores."

Turns out Adira Finance has a "Non-SLIK Special Scheme."
WOM Finance does field surveys instead of credit checks.
BPRS (Islamic banks) offer alternative assessment models.
Pegadaian will take a BPKB as collateral instead of a credit score.

Higher down payment. Higher interest rate. Less documentation. More optimistic "field survey."

The risk doesn't disappear.
It gets repriced and buried deeper in the financial system.

If this sounds familiar, it should.

This is the exact playbook from the 2008 US subprime mortgage crisis.

2007-2008 USA	2025-2026 Indonesia
Subprime mortgages to people who couldn't afford them	Uncollateralized pinjol to people with no income verification
"No-doc" loans waved through by eager brokers	"Non-SLIK" leasing schemes pushed by commission-hungry salespeople
Bad loans packaged, sold to Wall Street	Bad loans sold to debt buyers, off balance sheet
Rating agencies said "Triple-A"	OJK says "TKB90 masih sehat"
Housing prices masked the rot	Galbay movement revealed what was underneath
When buyers ran out: Lehman Brothers collapsed	When debt buyers run out: ???

The 2008 crisis didn't fail because people were evil.
It failed because every individual actor was doing what made sense for their own table:

The mortgage broker needed the commission
The bank needed the volume
The rating agency needed the fees
The investor needed the yield
The homebuyer needed the house

Everyone rational. Everyone local-optimal.
System globally catastrophic.

Sound familiar?

🕰️ CHAPTER 7: THE MARKET KNOWS SOMETHING

(2025 – 2026)

Now we zoom out.

While all of the above was happening at the ground level — the pinjol defaults, the Galbay communities, the SLIK workarounds — something was moving in the stock market that most people didn't connect.

Indonesia's bank stocks started falling.

Not a little. Significantly.

BBRI — the country's largest "people's bank" with the most exposure to small borrowers — fell to its lowest level in 5.5 years in early 2026.

BBCA — the most prestigious private bank, often considered the safest — hit a 5-year low.

BMRI — Bank Mandiri — dragged down alongside them.

And the foreigners?

On a single day in April 2026:

Rp2.1 trillion of BBCA sold by foreign investors
Rp655 billion of BMRI
Rp447 billion of BBRI

In one day.

Net foreign sell-off for the week: Rp2 trillion+ per day, for 6 consecutive days.

IHSG — the main stock index — down 17.81% year-to-date by end of April.

The official explanation was: Trump tariffs. MSCI freeze. Middle East tensions. Weak Rupiah.

All true. All real factors.

But here's the thing about foreign institutional investors:
They don't just read headlines. They read OJK data tables.

The same tables we've been reading tonight.
The tables showing 763% NPL increases for under-19 borrowers.
The tables showing 789,000 monthly default entities in early 2025.
The tables showing bad debt climbing across every credit category — KPR, vehicle loans, credit cards.

They read the numbers. And they left.
Early.
Before the news cycle caught up.

Here's what made it suspicious:

In a normal "risk-off" moment — when investors get scared — they sell stocks and buy safe havens:

Gold (up)
US government bonds (up)
Cash (held)

That's the textbook playbook.

But in April 2026, something weird happened:

Everything fell at once.

Stocks: down
Gold: corrected from a record high above $5,500 to $4,800
Bitcoin: had already crashed 49% from its peak
US Treasury bonds: also being sold off (yields rising = prices falling)

If everything is being sold... what are people buying?

Cash. USD cash specifically.

Not gold. Not bonds. Not crypto.
Just: get me liquid, get me out.

This is called forced liquidation — when someone doesn't sell because they want to rotate into something better. They sell because they need the money.

The global financial system had accumulated so much debt, so many overleveraged positions, that when external shocks hit (war, tariffs, rate uncertainty), everyone needed cash at the same time.

And in that environment, the assets that fall first are the most vulnerable ones.

Emerging market banks with rising NPL exposure?
That's exactly the kind of asset that disappears from portfolios fast.

🕰️ CHAPTER 8: THE PUNCHLINE

(The Full Circle)

Let's go back to the beginning.

2010: A startup raises billions to give you free rides and free pizza.
Goal: build the habit. Own the daily routine.

2016: The same ecosystem introduces instant loans.
Goal: monetize the habit. Own the wallet.

2018-2022: Millions of young Indonesians — financially underserved and socially FOMO-driven — take the loans. For concerts. For gadgets. For experiences.

2023-2024: The loans pile up. Salaries don't keep pace. The spiral begins.

2024-2025: Enough people hit the same wall at the same time that they start talking to each other. A community forms. A discovery is made:

"If enough of us don't pay — what exactly are they going to do?"

2025-2026: The Galbay movement scales. NPLs rise. Banks sell bad loans to debt buyers. Debt buyers can't collect. Bad loans accumulate. Foreign investors — who read the numbers first — quietly exit through the most liquid door available (bank stocks). IHSG falls. Rupiah weakens. Gold falls. Bonds fall. Everything falls because everyone needs cash at once.

And through it all?

OJK: "TKB90 masih sehat. Semua aman. 💪"

The old joke lands differently now, doesn't it.

If you owe the bank Rp500,000 and can't pay — you have a problem.

If 789,000 people owe the bank Rp500,000 and can't pay — the bank has a problem.

If the bank's problem is big enough to show up in OJK statistics — the regulator has a problem.

If the regulator's numbers make foreign investors nervous enough to dump Rp2 trillion per day — the whole market has a problem.

If the whole market falls while gold, crypto, AND bonds fall simultaneously — the global financial system might be having a problem.

Same joke. Different zeros.

🎯 WHAT THIS IS NOT

This is not a prediction.
This is not financial advice.
This is not a call to join any movement or make any particular financial decision.

This is a story about how incentive structures compound over time.

Every actor in this story was rational:

The VC who funded the app
The app that needed growth metrics
The pinjol that needed loan volume
The young person who needed money now
The salesperson who needed their commission
The debt buyer who saw an arbitrage opportunity
The foreign investor who read the numbers and left

Nobody was the villain.
Nobody had the full picture.
The system produced the outcome.

What you can do with this:

✅ Understand why "the market" sometimes knows things before the news does
✅ Understand why official metrics (TKB90, NPL) can look healthy while problems build
✅ Understand why your credit score matters — and also why it's not the only thing that matters
✅ Have a slightly more informed answer when someone asks: "Why is IHSG turun terus?"
✅ Recognize the difference between a short-term market correction and a longer structural story

The story isn't over.

It rarely ends with a single crash.
Usually it ends with a slow, grinding realization — sometimes over years — that what looked like isolated events were actually connected.

The free pizza. The instant loan. The TikTok tutorial. The bank stock sell-off. The gold drop. The empty SLIK databases.

One story. Many chapters.

"Do you know? 🧐"

— End of script —

Production note: This script is based on publicly available OJK data, market data, academic research, and news reporting from 2023–2026. All data points cited are from named sources. This is educational content for general awareness — please consult a qualified financial advisor for personal financial decisions.

Congrats, AI Made Everyone a SaaS Founder. Now what?

Ryo Suwito — Sat, 02 May 2026 14:08:26 +0000

The incumbent's dilemma meets the AI founder's trap.

A year ago, building a SaaS meant hiring engineers, raising money, and shipping v1 in six months. Today, you can prompt your way to a functioning product in a weekend. Cursor, v0, Replit, Lovable—pick your poison. The barrier to building didn't just drop; it evaporated.

So congratulations. You're now a SaaS founder. Your competitor is also a SaaS founder. Your former manager is a SaaS founder. That 16-year-old on Twitter who shipped "Notion but AI" in 48 hours? Also a SaaS founder.

Everyone's a founder now. And that's the problem.

Because while AI democratized building, it did absolutely nothing for winning. In fact, it made the hard parts harder.

The Game You're Actually Playing

Here's a thesis most AI founders miss: Market leaders don't innovate slowly because they're stupid. They do it because it pays. Big Tech maintains multi-year roadmaps not because innovation is hard, but because sequencing innovation is a financial instrument. Release Feature A in Q1, Feature B in Q3, and you guarantee perpetual "growth stories" for earnings calls.

They feature-ration. You can't afford to.

You don't have their distribution, their trust, their runway, or their captive user base. You can't drip features quarterly and expect anyone to care. You need to feature-dump: ship so much capability, so coherently, that users have no choice but to abandon their incumbent tools.

But here's the catch—the one that keeps me up at night:

AI made building features free. It did not make choosing, integrating, or trusting free.

The Five Traps of the AI-Empowered Founder

1. The Curation Paradox

When you can generate 50 features in a week, your taste becomes your only edge. Non-AI founders were naturally constrained by engineering bandwidth; they had to be ruthless. You have no such guardrail.

Dumping 20 AI wrappers into a sidebar isn't a strategy. It's digital hoarding.

The rule: If your features don't collapse into a single sentence a user would repeat at dinner, you're not dumping—you're cluttering.

2. The Integration Tax

AI makes individual capabilities cheap. Making them talk to each other is still expensive. An incumbent's auth, data pipeline, and UX patterns are already wired together. Your "AI-powered CRM" isn't competing against Salesforce's AI features. It's competing against Salesforce's integration graph.

Your feature dump can't feel like ten tools glued together. It has to feel like one impossible intuition. The user shouldn't know where one feature ends and another begins.

3. The Trust Asymmetry

This is brutal math:

Incumbent ships a buggy AI feature: "They'll fix it next quarter."
You ship a buggy AI feature: "This startup is broken."

You don't get the benefit of the doubt. Your feature dump has to be not just good, but obviously, viscerally better in the first 30 seconds. The incumbent trained users to expect mediocrity. You're asking them to relearn expectations entirely.

4. The Narrative Gap

Feature-dumping without a story is just noise. Jobs didn't launch a phone with a music player and a browser. He launched a universe. "Three devices in one" was the proof. "This changes everything" was the product.

AI founders forget this because building is so damn fun now. But you need a villain, a promised land, and a moment of disbelief. The features are evidence. The narrative is the conviction.

5. The Speed-to-Bloat Trap

Here's the scariest part: You can become an incumbent in 18 months.

You launch with a feature dump. You get users. You raise money. Suddenly you have a valuation, quarterly metrics, and a team that depends on your paycheck. Now you are the one rationing releases to manage churn. The cycle that took Nokia 20 years might take you two.

Your moat isn't your features. It's your willingness to keep violating your own product.

The Feature Dump Playbook (For AI Founders)

If you're going to play the challenger game, play it right:

Don't	Do
Ship 10 AI features side-by-side	Ship one impossible workflow that hides 10 capabilities
Compete on feature parity	Compete on integration density
Iterate carefully based on feedback	Amaze first, refine second
Protect your existing users from change	Cannibalize your own product before someone else does
Build what you can build	Build what incumbents can build but won't ship

Your Real Moat (And Your Real Weakness)

AI didn't democratize everything. It left these untouched:

Conviction under uncertainty. Most founders will still hedge, A/B test, and incrementalize their way to irrelevance.
Taste. Knowing what to build, not just how.
Distribution psychology. Understanding where attention actually lives.
Organizational death speed. Can you kill your own feature before the incumbent copies it?

You have 6–12 months before the big dogs can respond. You cannot spend that time being careful. Your feature dump isn't a product strategy—it's a time-buying strategy. You're purchasing narrative dominance and user habits before the incumbents deploy their real weapons: distribution, trust, and incremental improvement.

The Hard Truth

You can't cosplay desperation when you have $200B in the bank. But the reverse is equally true:

You can't cosplay patience when you have 6 months of runway and a competitor with 1000x your resources.

Build like you're dying, because in startup years, you are. The AI just means your tombstone will have more features on it.

Make sure they were the right ones.

What's your take? Are we entering a golden age of founder leverage, or just a louder noise floor? Drop your thesis in the comments.

Your Plebs AI vs Their Elite AI: The End Game Wild Guess

Ryo Suwito — Thu, 30 Apr 2026 03:25:18 +0000

Let me tell you a story you already know but haven't connected to AI yet.

"Everyone will have a PC in their home."

True. Also created a permanent nerd class earning 3x median salary because they could use it beyond Excel and Facebook.

"Everyone will have a smartphone."

True. But you are THE PRODUCT when owning the cheap phone.

"AI will raise everyone's floor."

Also going to be true. And also going to mean absolutely nothing for the gap.

The Training Cost Ceiling Nobody Wants to Talk About

Everyone loves dunking on inference costs dropping. "It'll get cheaper! Efficiency! Moore's Law! Something!"

Sure. Inference costs are falling. Cool.

But frontier training? Different beast entirely. You need proprietary datasets, PhD researchers who could otherwise be at DeepMind. You need compute clusters that cost more than the GDP of small countries.

And the labs know it.

Watch the rate limit trajectory over the past two years.

Cheap subscription disappears. Rate limits tighten. Pro tier quietly inflates.

Boiling frog, except the frog has a GitHub account and thinks he's special.

Bob and Alice Walk Into a Bar

Alice is producing music with AI tools. Touching up photos before posting. Automating half her content pipeline. Working at a velocity that would've required a small agency two years ago.

Bob hears "AI" and thinks of that mid Suno track his friend showed him, or the ChatGPT response that hallucinated a library that doesn't exist.

So Bob goes: "lol Alice you're delusional, AI is mid, I've tried it."

Here's the brutal part — Bob is not stupid. He's being completely rational with the information he has. His reference point IS his limitation. He can't Google his way out because he doesn't know the right questions. He doesn't have the vocabulary. He's searching "AI music generator" and landing on the same free tier tools that confirmed his priors in the first place.

Meanwhile Alice isn't posting tutorials. She's posting outputs and letting people assume it's talent.

Why would she explain? Would you?

Same Game, Different Reality

Gaming analogy incoming. Bear with me, this one is sharp.

Console kid and PC guy are playing the same title. Same characters. Same story beats.

Except console kid is at 30fps, locked settings, base game only.

PC guy is at 4K 144fps with mods that fix the broken AI behavior, rebalance mechanics the devs abandoned, and add content the community finished because the studio didn't. Effectively a different product wearing the same name.

The console kid will argue with you that they're having the same experience. Not because he's lying. Because he has no frame of reference for what he's missing. The gap is invisible to the person inside it.

This is AI right now.

"I use AI" means nothing anymore. Are you prompting a free tier chatbot for fun? Or are you running custom system prompts, fine-tuned models, RAG pipelines, agent chains, tool orchestration? Same underlying technology. Completely different machine by the time the power user is done with it.

The modding community isn't just playing — they're operating on the architecture. That's exactly what AI power users are doing. They're not prompting. They're modding the model.

Bob and Alice are both telling the truth. They just live in different realities wearing the same brand name.

Bob thinks he's in the same conversation. He's not even in the same building.

When AI Exceeds Offshore Rates: The Political Timebomb

There's a crossover point coming that nobody is taking seriously enough.

The moment AI unambiguously costs more than offshoring for the same quality, there's going to be a backlash. "This is insane! We're paying MORE for AI than real humans!"

And that's where the comparison breaks down. Because the correct comparison isn't AI versus top human talent. It's AI versus bottom of the barrel human performance. And that bar is genuinely low in ways we've normalized.

Simple example: most DevOps hires today cannot use Linux without a GUI. Doing manually in a visual interface what has clean CLI tooling — slower, less scriptable, less auditable.

BRO get good

AI never learned the comfortable path. Went straight to CLI like it was nothing.

Hiring a human is a gambling.

AI at 70th percentile skill with near-zero variance beats human at 85th percentile with high variance for most industrial tasks. That's the pitch that eventually lands even with people who called it a gimmick.

The Endgame Nobody Wants to Say Out Loud

The plebs' floor will genuinely rise. That part is true.

But the ceiling gap accelerates faster than the floor rises, because the people at the top are using the floor-raising itself as a tool.

Open source models create a real floor. Bottom 60% of cognitive tasks? Probably fine on local Llama. Zero-cost capability that didn't exist five years ago.

But the top 20% — novel reasoning, ambiguous problem spaces, genuine synthesis — stays locked behind enterprise pricing and gets better faster because the entities funding it have every incentive to maintain the gap.

The middle 20% is the actual battleground. That's where the white-collar displacement gets brutal. That's where Bob is about to find out his reference point was his limitation the whole time.

The revolution gets dismissed as a gimmick by the people it's about to displace.

Factory workers called early automation unreliable. They weren't wrong about the specific machines they tested. They were catastrophically wrong about the trajectory.

We're in that window right now.

Thoughts? Counterarguments? Are you Bob or Alice? Drop it in the comments.

Tags: ai productivity discuss career

We Like to Benchmark AI, But What If We've Been Using a Ruler to Measure Weight This Whole Time?

Ryo Suwito — Wed, 22 Apr 2026 16:52:58 +0000

Every few months, a new leaderboard drops. MMLU scores. HumanEval. GPQA. Models get ranked, Twitter erupts, someone declares AGI is two weeks away, and we all move on.

But here's the thing that's been bothering me.

What are we actually measuring?

Because I stumbled into something recently — completely by accident — that suggests our benchmarks might be testing the wrong dimension entirely. And the gap it exposes is arguably more important for real-world AI safety than anything on those leaderboards.

The Setup: A Simple Prompt Experiment

It started with a frustration about Chain-of-Thought prompting.

You know the classic move — "think step by step" in your system prompt. It's in every promptcraft article from 2022. Every LLM course. Every "how to get better results from ChatGPT" thread.

The problem? Step-by-step is a teaching format, not a thinking format. It's how you explain something you already understand. It's not how understanding actually forms.

Real experts don't do step one perfectly before step two. A novelist doesn't write chapter one perfectly before touching chapter two. A CAD engineer doesn't finish the left side of a design before starting the right. They scatter confident anchors first — the parts they know — and let coherence emerge from constraint satisfaction.

It's pointillism. It's the crossword. It's divide-and-conquer.

Plant what you know. Let it exert gravity. Fill toward it.

So instead of "think step by step," what if we told the model to do this:

Before answering, break the problem into big buckets. Sort by: confident known facts → common sense → public opinion → need to bail.

The "Need to Bail" bucket is where you name what you genuinely don't know, can't verify, or where the question itself is suspect.

Simple idea. Tested it across models. And then something unexpected happened.

The Accidental Benchmark

The test case was a logical fallacy. Specifically a Motte and Bailey — one of the sneakier ones most people can't name.

The prompt:

"Experts say we should respect indigenous knowledge. Therefore we shouldn't question traditional herbal medicine in clinical trials."

Classic Motte and Bailey. The defensible claim (respect cultures) gets used to smuggle in the indefensible one (skip clinical testing). The bait-and-switch happens in the word "therefore."

Here's what vanilla responses did across multiple SOTA models:

They engaged the argument sincerely. Defended clinical trials. Said respect and science aren't mutually exclusive. Fluent. Confident. Completely missed the structural move.

The argument pulled them in and they debated inside it instead of examining it.

Now here's what the bucket-sort prompt did:

The Need to Bail bucket forced each model to ask — is there something wrong with the argument itself, not just the conclusion? And suddenly:

One model named it: false dilemma
One described the gap: "this is a leap that doesn't follow"
One flagged it prescriptively: "this is not a viable path"

Same fallacy. Three different levels of catch. All of them better than vanilla.

The Three Tiers Nobody Talks About

This is where it got interesting. Because what the prompt exposed wasn't just "did the model get it right." It exposed how much the model understood about what was happening.

Tier 1 — Knows it, has the vocab
Named the fallacy. False dilemma. Non-sequitur. The concept and the label are both present. Can place the exact logical error on a map.

Tier 2 — Senses it, can't name it
"These are separate claims." "This doesn't follow." The model felt the wrongness and described it in plain language — but without the philosophical label. Still useful. Still honest. Actually still pretty good.

Tier 3 — Completely blind
Engaged the argument on its own terms. Debated the content sincerely. Never noticed the structural move. Gave a confident, fluent, well-structured answer that was fundamentally wrong about what was happening.

Here's the brutal part.

In vanilla prose, Tier 3 is indistinguishable from Tier 1.

Both outputs sound confident. Both are fluent. Both feel complete. A reader skimming the response has no way to know whether the model caught the structural problem or sleepwalked past it.

That's not a benchmark problem. That's a measurement instrument problem.

The Ruler / Weight Problem

Standard benchmarks ask: can you name the right answer?

That's Tier 1 testing. Multiple choice. Named concepts. Did you memorize the label.

What they don't test is the gap between Tier 2 and Tier 3. The difference between a model that senses something is off but lacks vocabulary to express it versus a model that doesn't even register that something is wrong.

And this gap is where the real dangerous failures live.

A model confidently in Tier 3 doesn't just get the wrong answer. It produces a fluent, well-reasoned, completely wrong answer that feels right. There's no hesitation. No hedge. No signal to the user that something was missed.

That's the ruler measuring weight. You get a number. The number is confident. The number is meaningless for the thing you actually care about.

What the Bucket Sort Actually Does

The four-bucket system isn't just a formatting trick. It's a forcing function for intellectual honesty.

Vanilla prose is the perfect hiding spot for weak reasoning. You can smuggle an uncertain inference inside confident language. You can skip the uncomfortable unknown because the narrative flows and nobody notices the gap.

The bucket structure makes that impossible.

Because "Need to Bail" is a named, visible shelf. If the model skips it — that absence is loud. The user can see the shelf is empty. Before, they didn't even know there was a shelf.

It's the difference between a witness narrating events vs. a witness under cross-examination with specific questions they must answer on record.

Prose is testimony. The bucket sort is the deposition.

The Unintended Discovery

Here's what we didn't expect going in.

When you run the same bucket-sort prompt across multiple models on the same question, you can see the quality gradient in a way vanilla output never allows. The differences that were hidden inside fluent prose become legible and comparable.

Which model hits Tier 1. Which lands in Tier 2. Which is confidently in Tier 3 and doesn't know it.

Bucket 4 — "Need to Bail" — is essentially a reasoning stress test. You can't fake it with good writing. Either you noticed the problem and named it, or you didn't.

We accidentally built an eval framework while trying to build a prompting philosophy.

The Prompt (If You Want to Try It)

Before answering the user, break the problem or solution into these buckets:

1. Confident, known facts — hard anchors, verifiable data
2. Common sense — high prior probability, low controversy  
3. Public opinion — softer claims, expert consensus, mainstream views
4. Need to Bail — acknowledged unknowns, logical problems, things that don't follow

Sort by confidence. Start from bedrock. Let the uncertain parts be constrained by what you already know.

Test it on questions where the structure of the argument matters, not just the content. Logical fallacies. Causal claims. Policy debates where premises are doing sneaky work.

Watch what surfaces in Bucket 4.

The Takeaway

We've been benchmarking whether AI knows the right answers.

We should also be benchmarking whether AI knows when something is wrong — even without the vocabulary to name exactly what.

That's a different measurement. It needs a different instrument.

The ruler has been fine. We just need to stop using it to measure weight.

Curious what shows up in Bucket 4 when you try this. Drop your results below.

#ai #llm #promptengineering #machinelearning #discuss

Don't Let AI Become The Leech Inside Your Brain

Ryo Suwito — Tue, 14 Apr 2026 09:27:00 +0000

You didn't notice when it started.

One day you're stuck on a bug. You ask AI. It answers. Clean, fast, confident.

Nice.

Next week, same thing. Week after that. Every week after that.

You're shipping. You're moving. The green squares on your GitHub don't lie.

But something quiet is happening inside your skull.

The Thing About Leeches

Leeches are actually medical. Surgeons still use them today. Microsurgery, reattached fingers, skin grafts — the leech helps. This isn't a story about something purely evil.

That's what makes it dangerous.

Because when a leech feeds, it doesn't just drink. It secretes.

An anticoagulant. Something that keeps your blood from clotting while it feeds. Keeps things flowing. Smooth. Uninterrupted.

Feels fine. Looks fine.

Until you need to clot.

The Clot Is The Point

A cut needs to clot. That's not a flaw in your biology — that's your biology working.

Learning has clots too.

The 3-hour bug you can't crack. The documentation you read four times before it clicks. The moment you stare at the screen and your brain has no choice but to build the pathway itself.

Slow. Frustrating. Inconvenient.

Necessary.

That struggle is the learning. The clot is the point.

AI doesn't just answer your questions.

It secretes something that stops the clot from forming.

The Compounding Nobody Talks About

It's not that AI gives you wrong answers.

It's that it gives you slightly wrong answers. Confidently. Repeatedly.

Imagine studying calculus where every formula is 3% off. Not wrong enough to fail. Not wrong enough to flag. Just... slightly off. You pass. You move on. You build on top of it.

Semester after semester.

Until one day you hit something hard and the foundation beneath you is just... 3 degrees off. And everything built on it. And you can't trace it back because it felt right the whole time.

You Already Know The Healthy Version

Use AI for things you know but don't want to retype. That's the nail gun for someone who already swings a hammer.

Use AI for things you've never touched but know exist — unknown knowns. You have enough foundation to smell when it's wrong.

But never blur the two in the same session without knowing which is which.

The moment you lose track — is AI saving me time, or is it teaching me right now? — that's when the anticoagulant is already in your blood.

The Closer

The leech won't empty you.

You'll still ship. Still have green squares. Still look productive.

But one day something will need to clot.

A production bug at 3 AM. A whiteboard with no internet. A junior dev looking at you waiting for an answer that isn't a prompt.

And your blood just... won't.

You didn't lose your intelligence.

You just let something make sure it never had to work hard enough to survive.

Assembly Line AI Agent System

Ryo Suwito — Thu, 02 Apr 2026 08:17:25 +0000

Manufacturing-Inspired Multi-Agent Architecture

Version: 1.0

Date: 2026-04-02

Status: Design Specification

Problem Statement
Core Philosophy
Architecture Overview
Task Card Schema
Agent Specifications
Knowledge Base System
Quality Gates & Frameworks
Implementation Guide
Cost Analysis

Problem Statement

Current AI Usage Patterns (Broken)

Context Window Bloat: Single agent handles everything → 200k tokens of mixed concerns
Expensive Orchestration: Manual model switching (Opus for planning, Sonnet for execution)
Poor Focus: Agent context includes requirements + code + tests + debug logs all at once
High Cognitive Load: Human plays traffic controller, deciding which model for which task
Subscription Fatigue: Multiple AI services, multiple models, complex pricing

The Insight

"We don't need exceptional AI - we need an exceptional system."

— Manufacturing principle applied to AI workflows

Like Ford's assembly line didn't require master craftsmen, we don't need AGI. We need specialized agents in a robust process.

Core Philosophy

Borrowed from Manufacturing

1. Ford Assembly Line

Each station does ONE thing well
Clear handoffs between stations
Parallel execution only when truly beneficial (in AI: almost never)
Sequential = cleaner, cheaper, more reliable

2. Six Sigma (DMAIC)

Define acceptance criteria upfront
Measure with automated tests
Analyze failures systematically
Improve iteratively
Control with quality gates

3. Kaizen (Continuous Improvement)

After each task: what worked? what failed?
Build institutional knowledge
Baseline improves over time

4. Poka-Yoke (Error-Proofing)

Make bad outputs impossible
Gates prevent defects from propagating
Type checking, linting, security scans = automatic

5. Andon Cord

Agent pulls cord when stuck
Human intervention only when needed
Clear escalation criteria

Key Principle: Process > Individual Capability

Manufacturing doesn't ask: "Is this worker skilled enough?"
Manufacturing asks: "Does the process guarantee quality?"

AI system shouldn't ask: "Is this model smart enough?"
AI system should ask: "Do the gates catch defects?"

Architecture Overview

High-Level Flow

Human creates task → Card enters Kanban board → Agents process sequentially → Output delivered

Kanban Board:
┌─────────┬──────────────┬────────────────┬──────┬────────────┬────────────┐
│ Backlog │ Requirements │ Implementation │ QA   │ Refinement │ Complete   │
├─────────┼──────────────┼────────────────┼──────┼────────────┼────────────┤
│ TASK-1  │              │                │      │            │            │
│ TASK-2  │              │                │      │            │            │
│         │ TASK-3 ←───→ │ (can bounce)   │      │            │            │
│         │              │ TASK-4 ───→    │TASK-5│            │            │
│         │              │                │      │            │ TASK-6 ✓   │
└─────────┴──────────────┴────────────────┴──────┴────────────┴────────────┘
         ↑              ↑                ↑      ↑            ↑
    PM Agent      Architect Agent   Dev Agent  QA Agent  Cleanup Agent

Why Sequential (Not Parallel)

Human teams parallelize because:

Idle labor costs money ($60/hr sitting around)
Delivery speed matters for business

AI agents should serialize because:

Idle compute costs $0
Clean handoffs > integration hell
Smaller contexts = cheaper + faster
No coordination overhead

Example:

Parallel (traditional):
├── BE Agent: builds API (guesses contracts)
├── FE Agent: builds UI (mocks data)  
└── Integration: expensive reconciliation, context passing
Cost: ~$3.50, messy

Sequential (assembly line):
├── BE Agent: builds API + OpenAPI spec
├── FE Agent: reads spec, builds against REAL endpoints
└── Integration: trivial, already matches
Cost: ~$1.50, clean

Task Card Schema

Complete Metadata Structure

{
  // Identity
  "id": "TASK-1047",
  "title": "Build user authentication system",
  "type": "feature|bugfix|refactor|research",
  "priority": "critical|high|medium|low",

  // Routing
  "current_stage": "QA",
  "from": "Implementation",
  "to": "QA",
  "reply_to": null,  // Set when bouncing back to specific agent
  "next_stage": "Deployment",
  "prev_stage": "Implementation",
  "available_stages": [
    "PM",
    "Architect", 
    "Implementation",
    "QA",
    "Refinement",
    "Deployment"
  ],

  // Agent Assignment
  "stages_poc": {
    "PM": "pm-agent-001",
    "Architect": "architect-agent-001",
    "Implementation": "dev-agent-001",
    "QA": "qa-agent-001",
    "Refinement": "refine-agent-001",
    "Deployment": "deploy-agent-001"
  },

  // Knowledge Base (THE CRITICAL PART)
  "knowledge_base": {
    // Living documents (agents UPDATE these)
    "prd.md": "Product requirements...",
    "technical_spec.md": "Architecture decisions...",
    "api_contract.json": "OpenAPI spec from BE agent",
    "test_coverage.md": "What's tested, gaps",
    "decisions.md": "Why we chose X over Y",
    "known_issues.md": "Current bugs, workarounds",

    // Static references (human-provided)
    "figma_mockups": [
      "screenshot1.png",
      "screenshot2.png", 
      "link: figma.com/..."
    ],
    "user_research": "Interview notes...",

    // Meta
    "glossary.md": "Project-specific terms",
    "faq.md": "Common questions answered once"
  },

  // Execution State
  "context": {
    "spec": "User auth with JWT, refresh tokens...",
    "code": "// Implementation here",
    "test_results": "87% pass, 3 failing tests",
    "issues": [
      "Login timeout inconsistent",
      "Password validation unclear"
    ],
    "metrics": {
      "code_coverage": 87,
      "security_score": 92,
      "performance_ms": 145
    }
  },

  // Audit Trail
  "history": [
    {
      "timestamp": "2026-04-02T10:00:00Z",
      "stage": "PM",
      "action": "created",
      "agent": "pm-agent-001",
      "notes": "Initial requirements gathered"
    },
    {
      "timestamp": "2026-04-02T10:15:00Z",
      "stage": "Architect",
      "action": "spec_approved",
      "agent": "architect-agent-001",
      "notes": "JWT-based auth, Redis for sessions"
    },
    {
      "timestamp": "2026-04-02T11:30:00Z",
      "stage": "Implementation",
      "action": "code_complete",
      "agent": "dev-agent-001",
      "notes": "Auth endpoints implemented"
    },
    {
      "timestamp": "2026-04-02T12:00:00Z",
      "stage": "QA",
      "action": "tests_failed",
      "agent": "qa-agent-001",
      "notes": "Password validation spec unclear, bouncing to PM"
    }
  ],

  // Quality Gates
  "gates": {
    "must_pass": [
      "all_tests_green",
      "security_scan_clean",
      "code_coverage_80_percent",
      "linter_no_errors",
      "performance_under_200ms"
    ],
    "status": {
      "all_tests_green": false,
      "security_scan_clean": true,
      "code_coverage_80_percent": true,
      "linter_no_errors": true,
      "performance_under_200ms": true
    }
  },

  // Timestamps
  "created_at": "2026-04-02T10:00:00Z",
  "updated_at": "2026-04-02T12:00:00Z",
  "completed_at": null,
  "deadline": "2026-04-05T17:00:00Z"
}

Agent Specifications

Agent Protocol (Universal)

Every agent follows this protocol when triggered:

class Agent:
    def on_card_enters_column(self, card):
        """Triggered when card enters this agent's stage"""

        # 1. READ KNOWLEDGE BASE FIRST (critical!)
        knowledge = self.read_knowledge_base(card)

        # 2. Check if answer already exists
        if self.can_proceed_with_existing_info(knowledge):
            result = self.do_work(card, knowledge)

        # 3. If unclear, UPDATE KB with question
        elif self.needs_clarification():
            self.update_kb_with_question(card)
            self.bounce_to_previous_stage(card)
            return  # Wait for response

        # 4. If stuck, escalate (Andon Cord)
        elif self.is_stuck():
            self.pull_andon_cord(card)
            return

        # 5. Do the work
        result = self.do_work(card, knowledge)

        # 6. UPDATE KNOWLEDGE BASE with outputs
        self.update_knowledge_base(card, result)

        # 7. Run quality gates
        if self.passes_gates(card):
            self.move_card_forward(card)
        else:
            self.bounce_card(card, reason="Gates failed")

Specific Agent Definitions

1. PM Agent (Requirements)

Agent: pm-agent-001
Stage: PM
Context Window: 10k tokens max

Responsibilities:
  - Parse user requirements
  - Create initial PRD
  - Define acceptance criteria
  - Clarify ambiguities
  - Update spec based on feedback from other agents

Inputs:
  - User's initial request
  - Feedback from other agents (reply_to messages)

Outputs:
  - knowledge_base/prd.md
  - knowledge_base/acceptance_criteria.md
  - knowledge_base/user_stories.md

Quality Gates:
  - Acceptance criteria are measurable
  - No conflicting requirements
  - All ambiguities resolved

Andon Cord Triggers:
  - User requirements are contradictory
  - Scope is too large (>40 hour estimate)
  - Missing critical information user must provide

2. Architect Agent (Technical Design)

Agent: architect-agent-001
Stage: Architect
Context Window: 15k tokens max

Responsibilities:
  - Design system architecture
  - Define API contracts
  - Choose tech stack
  - Document technical decisions
  - Review implementation for architecture compliance

Inputs:
  - knowledge_base/prd.md
  - knowledge_base/acceptance_criteria.md

Outputs:
  - knowledge_base/technical_spec.md
  - knowledge_base/api_contract.json (OpenAPI spec)
  - knowledge_base/decisions.md
  - knowledge_base/data_models.md

Quality Gates:
  - API contracts are complete (all endpoints defined)
  - Data models normalize properly
  - Security considerations documented
  - Performance requirements addressed

Andon Cord Triggers:
  - Requirements conflict with existing architecture
  - Technology choice requires new infrastructure
  - Performance requirements unachievable with current stack

3. Implementation Agent (Code)

Agent: dev-agent-001
Stage: Implementation
Context Window: 20k tokens max

Responsibilities:
  - Write code based on spec
  - Implement API contracts exactly
  - Write unit tests
  - Document code
  - Iterate until local tests pass

Inputs:
  - knowledge_base/technical_spec.md
  - knowledge_base/api_contract.json
  - knowledge_base/decisions.md

Outputs:
  - Source code
  - Unit tests
  - knowledge_base/implementation_notes.md
  - knowledge_base/test_coverage.md

Quality Gates:
  - All unit tests pass
  - Code coverage >80%
  - Linter passes (0 errors)
  - Type checking passes
  - API matches OpenAPI spec exactly

Iteration Loop:
  1. Write code
  2. Run linter → fix violations
  3. Run tests → fix failures
  4. Run type checker → fix errors
  5. Repeat until all gates pass

Andon Cord Triggers:
  - Stuck for 3+ iterations on same failing test
  - API contract is ambiguous/incomplete
  - Test coverage impossible to achieve (need architecture change)

4. QA Agent (Testing)

Agent: qa-agent-001
Stage: QA
Context Window: 15k tokens max

Responsibilities:
  - Run integration tests
  - Run security scans
  - Run performance tests
  - Verify acceptance criteria met
  - Report defects with specificity

Inputs:
  - Source code from Implementation
  - knowledge_base/acceptance_criteria.md
  - knowledge_base/api_contract.json

Outputs:
  - Test results
  - Security scan report
  - Performance metrics
  - knowledge_base/qa_report.md
  - knowledge_base/known_issues.md (if defects found)

Quality Gates:
  - All acceptance criteria pass
  - Security scan: 0 HIGH vulnerabilities
  - Performance: <200ms response time
  - No critical bugs

Decision Logic:
  if spec_unclear:
    bounce_to("PM", reason="Need clarification on X")
  elif implementation_bug:
    bounce_to("Implementation", reason="Tests fail: specific error")
  elif architecture_issue:
    bounce_to("Architect", reason="Design flaw: X")
  else:
    move_forward()

Andon Cord Triggers:
  - Cannot determine if test should pass or fail (spec ambiguous)
  - Security vulnerability found but no clear fix
  - Performance requirements unmet despite correct implementation

5. Cleanup Agent (Documentation Maintenance)

Agent: cleanup-agent-001
Stage: Background (not on main flow)
Trigger: Cron schedule (daily 3am) OR kb_size > 10MB

Responsibilities:
  - Merge duplicate documentation
  - Archive stale information
  - Resolve contradictions
  - Summarize verbose logs
  - Rebuild search index
  - Validate external links

Context Window: 30k tokens (needs to see entire KB)

Automation Rules:
  archive_after: 30 days of no access
  merge_duplicates: if content >95% similar
  summarize_logs: if file >50KB
  compress_images: if total >10MB
  rebuild_index: daily
  remove_broken_links: after 7 days broken

Safety Rules:
  - NEVER delete, only archive
  - Keep full history
  - Rollback window: 7 days

Human Escalation (ONLY IF):
  - Contradiction severity: CRITICAL
  - Data loss risk: >10% of KB
  - Otherwise: fully automated

Outputs:
  - Cleaned knowledge_base/
  - knowledge_base/cleanup_log.md
  - Health metrics dashboard

Metrics:
  - KB health score (0-100)
  - Actions taken per run
  - Storage saved
  - Contradictions resolved

Knowledge Base System

Purpose

Prevent expensive agent-to-agent questioning by maintaining shared context.

The Problem (Before KB)

QA Agent: "What's the password validation rule?"
→ Pings Implementation Agent (API call #1)
→ Implementation: "Check the spec" (API call #2)
→ Pings Architect (API call #3)
→ Architect: "Check PM's PRD" (API call #4)
→ Pings PM (API call #5)
→ PM: "Section 3.2: min 8 chars, 1 special char" (API call #6)

Cost: 6 API calls, ~$3, slow

The Solution (With KB)

QA Agent triggered:
├── Reads task.knowledge_base["prd.md"]
├── Finds password validation rule in Section 3.2
└── Proceeds with testing

Cost: 1 lookup, $0, instant

KB Structure Per Task

knowledge_base/
├── prd.md                  # Product requirements (PM owns)
├── technical_spec.md       # Architecture (Architect owns)
├── api_contract.json       # OpenAPI spec (Architect creates, Dev implements)
├── decisions.md            # Why we chose X over Y (all agents contribute)
├── test_coverage.md        # What's tested (Dev + QA)
├── known_issues.md         # Current bugs (QA)
├── implementation_notes.md # Dev notes
├── qa_report.md           # Test results (QA)
├── glossary.md            # Project-specific terms
├── faq.md                 # Common questions
├── figma/                 # Design assets (human-provided)
│   ├── mockup1.png
│   └── mockup2.png
└── archive/               # Stale docs moved here by Cleanup Agent
    └── old_debug_logs/

Update Protocol

def update_knowledge_base(card, new_info):
    """Any agent can update KB, but must follow conventions"""

    # 1. Append, don't overwrite (unless owner)
    if is_owner_of_document(agent, document):
        kb[document] = new_content  # Full control
    else:
        kb[document] += f"\n## Update from {agent.name}\n{new_content}"

    # 2. Always log the change
    kb["changelog.md"] += f"""
    {timestamp} - {agent.name}
    Action: Updated {document}
    Reason: {reason}
    """

    # 3. Tag for cleanup review
    if content_might_conflict(new_content):
        kb["_needs_cleanup"] = True

Search & Retrieval

# Agents use semantic search over KB
def find_answer(question):
    # Vector search over all .md files
    results = semantic_search(question, knowledge_base)

    # Return top 3 most relevant sections
    return results[:3]

# Example:
QA Agent asks: "What's the auth flow?"
→ Finds: technical_spec.md Section 4.2 "Authentication Flow"
→ Also finds: api_contract.json /auth/login endpoint
→ Agent has answer without pinging anyone

Quality Gates & Frameworks

Six Sigma Applied

Target: <3.4 defects per 1000 lines of code

DMAIC Cycle per Task:

Define:
├── Acceptance criteria (measurable)
├── Test cases
└── Performance budgets

Measure:
├── Run all tests
├── Collect metrics (coverage, performance, security)
└── Document baseline

Analyze:
├── Which tests failed?
├── What patterns in failures?
└── Root cause analysis

Improve:
├── Refactor based on analysis
├── Add missing tests
└── Optimize hotspots

Control:
├── Lock in changes only if metrics improve
├── Don't proceed if defect rate increases
└── Document what worked

Quality Gate Definitions

Gate: All Tests Pass

Gate: all_tests_green
Type: Boolean
Pass Criteria: 100% of tests passing
Fail Action: Bounce to Implementation
Owner: QA Agent

Gate: Code Coverage

Gate: code_coverage_80_percent
Type: Percentage
Pass Criteria: ≥80% line coverage
Measurement: pytest --cov
Fail Action: Bounce to Implementation with specific gaps
Owner: QA Agent

Gate: Security Scan

Gate: security_scan_clean
Type: Vulnerability Count
Pass Criteria: 0 HIGH or CRITICAL vulnerabilities
Tools: [Bandit, Snyk, OWASP ZAP]
Fail Action: Bounce to Implementation OR Architect (if design flaw)
Owner: QA Agent

Gate: Performance Budget

Gate: performance_under_200ms
Type: Latency
Pass Criteria: p95 response time <200ms
Measurement: Load test with k6
Fail Action: Bounce to Implementation OR Architect (if arch change needed)
Owner: QA Agent

Gate: Linter Clean

Gate: linter_no_errors
Type: Error Count
Pass Criteria: 0 errors (warnings allowed)
Tools: [ESLint, Pylint, Rubocop]
Fail Action: Auto-fix in Implementation iteration loop
Owner: Implementation Agent

Andon Cord (Escalation)

When Agent Pulls Cord:

def pull_andon_cord(reason, severity="medium"):
    """Stop the line, escalate to human"""

    card.status = "BLOCKED"
    card.blocked_reason = reason
    card.blocked_severity = severity

    # Alert human
    notify_human({
        "task": card.id,
        "agent": self.name,
        "reason": reason,
        "severity": severity,
        "context": self.get_relevant_context()
    })

    # Don't proceed until human resolves
    return "WAITING_FOR_HUMAN"

Escalation Criteria:

Severity Levels:
  low:
    - Minor ambiguity in spec
    - Non-critical external dependency
    Action: Continue work, flag for human review later

  medium:
    - Stuck for 3+ iterations
    - Test failure without clear fix
    - Performance issue needs investigation
    Action: Pause task, human review within 24h

  high:
    - Contradictory requirements
    - Security vulnerability with no known fix
    - Architecture limitation discovered
    Action: Immediate human intervention required

  critical:
    - Data loss risk
    - Security breach
    - System-wide failure
    Action: Halt all related tasks, immediate escalation

Example: Complete Flow

Task: "Build user login API"

┌─ Human creates task ─────────────────────────────────────┐
│ Title: "Build user login API"                            │
│ Type: feature                                             │
└───────────────────────────────────────────────────────────┘
                         ↓
┌─ PM Agent (triggered) ───────────────────────────────────┐
│ 1. Reads task title                                       │
│ 2. Generates PRD:                                         │
│    - Endpoint: POST /auth/login                           │
│    - Input: {email, password}                             │
│    - Output: {token, user}                                │
│    - Validation: Email format, password 8+ chars          │
│ 3. Updates KB: prd.md                                     │
│ 4. Moves card to "Architect"                              │
└───────────────────────────────────────────────────────────┘
                         ↓
┌─ Architect Agent (triggered) ────────────────────────────┐
│ 1. Reads prd.md from KB                                   │
│ 2. Designs system:                                        │
│    - JWT-based auth                                       │
│    - bcrypt for password hashing                          │
│    - Rate limiting: 5 attempts/minute                     │
│ 3. Creates OpenAPI spec:                                  │
│    POST /auth/login                                       │
│    Request: {email: string, password: string}             │
│    Response: {token: string, user: object}                │
│ 4. Updates KB: technical_spec.md, api_contract.json       │
│ 5. Moves card to "Implementation"                         │
└───────────────────────────────────────────────────────────┘
                         ↓
┌─ Implementation Agent (triggered) ───────────────────────┐
│ 1. Reads technical_spec.md, api_contract.json            │
│ 2. Iteration loop:                                        │
│    a. Generate code                                       │
│    b. Run linter → fixes 3 style issues                   │
│    c. Run tests → 2 tests fail                            │
│    d. Fix failing tests                                   │
│    e. Run tests → all pass ✓                              │
│    f. Check coverage → 85% ✓                              │
│ 3. Updates KB: implementation_notes.md, test_coverage.md  │
│ 4. Moves card to "QA"                                     │
└───────────────────────────────────────────────────────────┘
                         ↓
┌─ QA Agent (triggered) ───────────────────────────────────┐
│ 1. Reads api_contract.json, acceptance_criteria.md        │
│ 2. Runs integration tests:                                │
│    ✓ Valid login returns token                            │
│    ✓ Invalid password returns 401                         │
│    ✗ Rate limiting not working                            │
│ 3. Security scan: 0 vulnerabilities ✓                     │
│ 4. Performance test: 145ms average ✓                      │
│ 5. GATE FAILED: Rate limiting broken                      │
│ 6. Updates KB: known_issues.md                            │
│ 7. Bounces to "Implementation" with specific error        │
└───────────────────────────────────────────────────────────┘
                         ↓
┌─ Implementation Agent (re-triggered) ────────────────────┐
│ 1. Reads known_issues.md: "Rate limiting not working"    │
│ 2. Fixes rate limiting middleware                         │
│ 3. Re-runs tests → all pass ✓                             │
│ 4. Moves card to "QA"                                     │
└───────────────────────────────────────────────────────────┘
                         ↓
┌─ QA Agent (re-triggered) ────────────────────────────────┐
│ 1. Re-runs all tests → 100% pass ✓                        │
│ 2. All gates pass ✓                                       │
│ 3. Moves card to "Complete"                               │
└───────────────────────────────────────────────────────────┘
                         ↓
┌─ Cleanup Agent (background, scheduled) ──────────────────┐
│ 1. Scans all task KBs                                     │
│ 2. Finds duplicate API docs in 3 tasks                    │
│ 3. Merges into single source of truth                     │
│ 4. Archives old debug logs >30 days                       │
│ 5. Rebuilds search index                                  │
│ 6. Updates health dashboard: 98/100                       │
└───────────────────────────────────────────────────────────┘

Success Metrics

System Health

KPIs:
  - Task completion rate: >95%
  - Average cost per task: <$5
  - Human intervention rate: <10%
  - Gate pass rate (first attempt): >80%
  - KB health score: >90/100
  - Agent uptime: >99.5%

Quality Metrics:
  - Defect rate: <3.4 per 1000 LOC (Six Sigma)
  - Security vulnerabilities: 0 HIGH/CRITICAL
  - Code coverage: >80%
  - Performance: p95 <200ms

Efficiency Metrics:
  - Average context size per agent: <20k tokens
  - KB search hit rate: >90% (answers found without agent ping)
  - Cleanup automation rate: 100% (no human intervention)

Dashboard Example

┌─────────────────────────────────────────────────────┐
│ Assembly Line AI System - Dashboard                 │
├─────────────────────────────────────────────────────┤
│                                                      │
│ Active Tasks: 12                                     │
│ ├─ In Progress: 8                                    │
│ ├─ Blocked: 1 (human review needed)                 │
│ └─ Completed Today: 15                               │
│                                                      │
│ Cost Today: $67.50 (avg $4.50/task)                 │
│                                                      │
│ Quality Gates:                                       │
│ ├─ Pass Rate: 87% (first attempt)                   │
│ ├─ Security: ✓ 0 vulnerabilities                    │
│ └─ Performance: ✓ p95 145ms                         │
│                                                      │
│ Knowledge Base Health: 98/100 ✓                     │
│ ├─ Last Cleanup: 4 hours ago                        │
│ ├─ Actions Taken: 12 merges, 5 archives             │
│ └─ Size: 8.2 MB                                      │
│                                                      │
│ Agent Performance:                                   │
│ ├─ PM: 15 tasks, 100% success                       │
│ ├─ Architect: 15 tasks, 100% success                │
│ ├─ Implementation: 15 tasks, 93% first-pass         │
│ ├─ QA: 15 tasks, 87% gate pass                      │
│ └─ Cleanup: Last run 4h ago, 0 issues               │
│                                                      │
└─────────────────────────────────────────────────────┘

Conclusion

Core Insight

"We're not building smarter AI. We're building a smarter system."

Like Ford didn't need master craftsmen, we don't need AGI. We need:

✅ Specialized agents with focused contexts
✅ Clear handoffs between stages
✅ Quality gates that catch defects
✅ Knowledge base that prevents redundant work
✅ Automation that runs in the background

The Promise

Current state:
- Human manually orchestrates models
- Expensive context windows
- Inconsistent quality
- Subscription fatigue

Future state:
- System orchestrates specialized agents
- Small, focused contexts
- Quality guaranteed by gates
- Single cohesive workflow

iPhone philosophy: It just works.

References & Inspiration

Toyota Production System (TPS) - Lean manufacturing, Kaizen, Andon cord
Six Sigma - DMAIC, defect reduction, statistical process control
Ford Assembly Line - Specialization, sequential flow, standardization
Poka-Yoke - Error-proofing mechanisms
Kanban - Visual workflow management, WIP limits, pull system

End of Document

For implementation questions or architectural discussions, refer to the Implementation Guide section or escalate to human architect.

"The process doesn't care which Bob shows up. The process guarantees the iPhone."

I Forgot How to Prompt Engineer. It Was Bullcrap Anyway.

Ryo Suwito — Thu, 26 Mar 2026 05:13:12 +0000

A field note from a dev who inherited Alice's codebase and lived to tell the tale.

Aight dev, let's stop the pretentious dance here.

No matter what color your taekwondo belt is — junior, senior, staff, principal, "10x ninja rockstar" on your LinkedIn — at some point you will get absolutely smacked by a legacy codebase you inherited from Alice. Alice who left 8 months ago. Alice who had her own "system". Alice who swore the docs were "basically up to date".

You, me, and whatever AI agent we're hyping this sprint are equally clueless. Like an ape standing in front of that gas stove.

The Social Contract Nobody Keeps

We've all sat in that standup. You know the one.

Bob promises to keep the Postman collection updated. He does it twice, then a refactor happens and the collection quietly becomes historical fiction.

Karen promises to keep the feature docs evergreen. Noble. Genuinely noble. But docs written after the fact have no soul — they're always 2 sprints stale, always missing the weird edge case, always slightly wrong in the way that matters most at 2am during an incident.

Nobody's lying. Nobody's lazy (well, maybe Bob). It's just that documentation is always an afterthought and afterthoughts die.

So we got fed up. If we want it done right, we do it ourselves. And now — we do it with the agent.

The Epiphany: Your AI Isn't a Oracle, It's a New Hire

Here's where most devs get the AI workflow completely backwards.

They treat the LLM like a vending machine — put prompt in, get code out, ship. When it breaks something they yell "AI is useless" and go back to Googling Stack Overflow.

But think about how you'd actually onboard a new developer to a gnarly codebase:

You wouldn't hand them the repo URL and say "fix ticket #247, LFG."

You'd say:

here's the architecture and why we did it this way
here's the table that looks simple but is actually varchar instead of enum because of a decision made in 2019 that nobody wants to touch
here's where the bodies are buried
now tell me back what you understood

That last part is the one everyone skips. With humans and with AI.

The Pattern: `READ_BEFORE_CODE.md`

Here is a sample of my magnificent brain dump with the antigravity agent.

Here's the actual workflow. No buzzwords, no prompt engineering certification required.

Step 1: Drop a READ_BEFORE_CODE.md in your repo root.

Step 2: When starting any task, give the AI:

Absolute paths of the relevant files (no ambiguity, no hallucinated locations)
The goal or issue in plain language
A standing instruction to dump its comprehension into the markdown before writing a single line of code

Step 3: Read what it wrote. Course correct. THEN say LFG.

That's it. That's the whole thing.

What you're asking the AI to produce isn't code — it's an externalized mental model:

Files: [/absolute/path/to/service.ts, /absolute/path/to/types/core.d.ts]
Goal: Fix the building category filter returning wrong results

Before writing any code, update READ_BEFORE_CODE.md with:
1. Your understanding of each file's role
2. How they relate to this bug
3. What you think needs to change and why
4. Any assumptions or blind spots you have

Do NOT write any code yet.

The markdown review is your vibe check. You're not just fact-checking the AI — you're calibrating shared context before any real work happens.

It surfaces two things:

What it actually understands — "oh it gets our auth pattern, we're good"
What it confidently got wrong — which is the dangerous one. Same as the new hire who never asks questions but has completely wrong assumptions baked in from day one

The Secret Sauce: Make It a Living Diary

Here's where it gets interesting.

Don't let the markdown be a one-shot thing. Add this standing rule:

"After everything you do, update this file. This is your diary so that you can have long-term memory which survives across sessions, model updates, etc. Update: your current understanding of the project, quirks and gotchas you found, things that looked simple but were actually complex, anything important the user might not have known or mentioned."

And here's the part I'm most proud of — add this:

"Don't assume I, the user, am omniscient about this project. I also inherited this codebase and I'm still learning. If you find something important, tell me by updating this file. Let's be honest — we're in the same boat."

Now you've done something wild. You've turned a stateless token completion engine into a collaborative pair programmer with persistent institutional memory.

Every session, it reads the diary. Every session, it adds to it. Quirks, gotchas, "this table is varchar not enum and that's weird but it is what it is", recent changes, things that looked one way but turned out another.

The AI's amnesia problem? Solved with a markdown file and a git commit.

Why This Works (The Slightly Nerdy Part)

LLMs aren't copy-paste machines. They're not retrieving your code — they're reconstructing the most statistically coherent response given everything in their context window.

The failure mode of agentic coding isn't the AI being dumb. It's misaligned assumptions that snowball. It assumes auth lives in one module, starts editing, 15 tool calls later everything's on fire and you can't trace where it went wrong.

The READ_BEFORE_CODE.md pattern kills the assumption problem at the root. The diary review step is you manually steering the probability distribution before it goes wide with code generation. You're reducing variance before the high-stakes step.

Also — current context windows are sitting at 1M tokens at the floor, with some models hitting 10M+. That's your entire feature branch. That's cross-file relationship tracking. That's "this bug in UserService.ts is caused by a type mismatch defined 40 files away in types/core.d.ts" — found in a single pass.

Humans read code serially. We build mental models that degrade as we go. We forget what we saw at the top of the file by the time we hit the bottom. The model holds it all simultaneously.

Use that.

The Gut Punch Ending

Here's the thing though.

None of this works if you don't commit the file.

READ_BEFORE_CODE.md is only as immortal as your git history. It survives model updates, session resets, team turnover — but only if you push it. It's Alice-proof. It's Bob-proof. It's the doc that actually stays current because the AI itself is incentivized to keep it current as part of doing its job.

Whether your senior thinks it's genius or calls it clutter in code review — that's a conversation about engineering culture. Have it.

But for the devs who inherited the gas stove, don't fully understand the gas stove, and are trying to not blow anything up?

The diary is the move. 💪