Comprehension debt finally has a name. The popular cure — write more docs — inherits the gap it's meant to close. What actually pays it down.
Your vibe-coded app caught on and now people pay for it — but you can't fully explain it. Build a mental model without reading every line, top-down.
Your product works. On launch day someone asks what it does at the edges — and you'd have to open the file to answer. That gap is the real launch risk.
Vibe-coding got you a working product you can't speak for. Reclaiming it isn't slowing down — it's re-authoring what you shipped, behavior by behavior.
You own a product you can't explain — acquired, inherited, or vibe-coded with AI. Here's how to read code you didn't really write, behavior by behavior.
You vibe-coded a working product. Users use it. You can't speak for it without reading every line. The product is yours — you just don't know it yet.
A spec extracted from code reads what is there, not what was decided — so placeholders and fallbacks get promoted to intent. Sign-off is the missing step.
Execution memory has tooling. Decision memory is emerging. The behavior layer — what your product promises to do — is the one almost nobody has built yet.
Engineers now make product calls, and the reasoning ends up in Slack threads and PR comments. Here is where to put it so the next person can find it.
AI made the rewrite cheap; recreating years of product decisions from memory did not get cheaper. How to keep the decisions when you throw away the code.
Shipping fast with AI agents feels productive. But the costliest mistake isn't bad code — it's building confidently when nobody wrote down what was decided.
PRDs capture intent. Tests verify assertions. Between them, there's no artifact tracking what the product promises — grounded in code, confirmed by humans.
When an outsourcing engagement wraps up, product knowledge walks out the door. A living behavior spec keeps it in the codebase — not in someone's head.
AI can extract product logic from your codebase. Stewie builds a living behavior spec your whole team can read — no code, no docs, no waiting on engineers.
Product owners confirm behaviors. BAs clarify logic. QA knows what to protect. New hires onboard fast. Vendors skip reverse-engineering. One shared contract.
Leaders shouldn't need three meetings to verify whether a product decision was implemented correctly. A living behavior spec is the direct line.
Your agent ships code that passes review and still breaks a product promise. It is not a capability gap — it is the product context no rules file gives it.
Shipping fast with AI coding tools is genuinely good. The problem isn't the speed — it's what gets left behind. Product reasoning doesn't survive the vibe.
A field guide to the .pbc.md format — the structured blocks that make up a Product Behavior Contract: behaviors, triggers, outcomes, and provenance.
Product knowledge lives in heads, not docs. Here's why that gap compounds — and what a behavior spec does about it.
