AI helped me ship faster. Then I forgot what my product actually does.
Hey IH,
Quick story behind this one.
Earlier this year I shipped an app fast using AI agents — mostly Codex CLI and Claude Code.
A couple of months later I sat down to add a new pricing tier. Should have been an afternoon.
I lost the whole day re-reading my own billing code because the change hinged on a question I couldn't answer:
When someone upgrades mid-cycle, do their new limits kick in right away, or at the next cycle?
I'd wired that logic myself months earlier, and I had no memory of which way I'd chosen.
Then I found six files I didn't remember opening and three integrations I didn't remember choosing.
Everything was technically correct. But I no longer owned it in the way that mattered: I couldn't explain why the product behaved the way it did.
I started calling this comprehension debt.
Not technical debt. Technical debt is code you know is messy.
Comprehension debt is the gap between what your product now does, what you think it does, and what you can actually prove from the repo.
AI agents make this worse in a strange way.
They help you ship faster, but your product starts changing at AI speed while your mental model still grows at human speed.
That's the problem I built Stewie Reflect around.
I wanted a way to read what I shipped in product terms — not reopen every file and reconstruct my own product decisions from scratch.
Stewie Reflect takes a snapshot of a GitHub repo and generates an owner's manual for the product — not a code walkthrough.
The manual is organized around product behavior:
- what the product appears to promise users
- what actually happens in the code
- where auth, billing, limits, integrations, and edge cases live
- which behaviors are clearly supported by evidence
- where the repo is ambiguous or silent
That last part matters most to me. I don't just want prose about my codebase. I want to know what product behaviors I can actually trust.
The shape I was after is closer to a manual than docs.
Docs are referenced.
A manual is read.
Live today as a freemium beta:
- free to generate and preview from your own repo
- you get a real chapter plus a map of every area and finding
- $19 beta unlocks the full manual + Markdown export
- one repo per unlock
- async generation in the background
The format underneath is open source too: Product Behavior Contract, MIT-licensed at github.com/stewie-sh/pbc-spec.
Link: stewie.sh/for/vibe-coders
The sample manual on the landing page was generated from a real codebase. You can read a chapter and click through to the evidence before deciding if it's useful.
What I'm trying to validate:
Is “I can't confidently explain what my AI-built product actually promises and does anymore” a real pain for other builders, or just my own founder/developer anxiety?
And more concretely:
Which part of your own product have you been avoiding because you don't remember designing how it should behave?
How we built a Hindi + English kids learning app in Unnao with zero budget
Launched on Product Hunt today: budget hosting where the whole pitch is honesty
Also cognitive load is a new bottle-neck that hits hard. Especially founders can with AI to even more at the same time, all over the place. Keeping focus and deliver value is the skill to master.
Comprehension debt is exactly the right name for it and I haven't seen anyone describe it this clearly before. Technical debt is visible. You can see the messy code, the missing tests, the quick fix that became permanent. Comprehension debt is invisible until it bites you. You don't know you have it until you sit down to make a change and realise you can't confidently explain what the system is doing or why it was built that way. The problem with AI-assisted development is that execution velocity separates from understanding velocity permanently. The code ships faster than your mental model can absorb it. And then six features later, you have a product that works but that nobody, including the person who built it, fully owns. The only real answer is to capture intent at the point of decision, not reconstruct it from code after the fact. What was the requirement? What constraint shaped the implementation? Why was this approach chosen over the obvious alternative? That has to live somewhere outside the code itself, because the code only tells you what was built, not what was meant. The manual framing for your product is a good instinct, it's organised around behaviour, not files. What's the hardest type of product decision to represent in the format you've built?
'Comprehension debt' is exactly the right name for this. The gap between what your product does and what you can actually prove it does is a completely different problem from messy code — and it's one most tools don't address. The billing example is perfect: that's not a code question at all, it's a product contract question, and the repo quietly assumes you remember what you decided. I've hit this building in the AI app space — the more AI helps you ship, the faster the reasoning behind decisions dissolves. Curious whether the manual format helps most at the 'why did I build it this way' layer or more at the 'what does it actually do' layer — those feel like different problems to me.
What I found interesting wasn't the idea of comprehension debt itself.
It was the moment where a very personal frustration turned into a product.
Those sometimes become great companies.
Other times they stay extremely real problems that mostly matter to the person who experienced them.
Figuring out which side you're on feels like the harder question here.