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 part of my product fast using AI agents — mostly Codex CLI and Claude Code.
A couple of months later I sat down to add a new pricing tier. It should have been an afternoon.
Instead I lost the whole day re-reading my own billing code because the change depended on a question I couldn't answer:
When someone upgrades mid-cycle, do their new limits kick in immediately, or at the next billing cycle?
I'd written that logic myself a few months earlier.
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.
Nothing was obviously broken.
But I no longer owned the product in the way that mattered: I couldn't explain why it 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 actually does
- what you think it does
- what you can actually prove from the repo
AI agents make this worse in a strange way.
They help your product evolve at AI speed while your mental model still grows at human speed.
That's the problem I built Stewie Reflect around.
Instead of reading code file by file, I wanted to read my own product again.
Not a code walkthrough.
An owner's manual.
Each manual is organized around product behavior:
- what the product appears to promise users
- what actually happens in the code
- where billing, auth, limits, integrations and edge cases live
- which behaviors are supported by evidence
- where the repo is silent or ambiguous
That last point matters most to me.
I'd rather see "unknown" than a confident hallucination.
The shape I was after is closer to a manual than documentation.
Docs are referenced.
Manuals are read.
Current beta
- Free: generate a manual and preview it
- Includes one real chapter plus a map of findings
- $19 one-time unlock for the full manual + Markdown export
- One repository per unlock
- Async generation
I'm also open-sourcing the underlying Product Behavior Contract (PBC) specification separately because I think the long-term solution is capturing intended behavior before it disappears, not reconstructing it afterward.
- Product: https://reflect.stewie.sh
- Sample manual: https://reflect.stewie.sh/#/manual
- PBC spec: https://github.com/stewie-sh/pbc-spec
What I'm really trying to validate isn't whether AI helps people ship faster.
It's this:
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 anxiety?
And one more question:
Which part of your own product have you been avoiding because you no longer remember how it's supposed to behave?
This hits close to home. I've been building a Chrome extension (Uniclip) and noticed the same drift — AI let me ship features in days that would have taken weeks, but the mental model of what the product actually does hasn't kept up.
The "comprehension debt" framing is sharp. It's not just about code documentation; it's about the gap between intended behavior and actual behavior becoming invisible. Your "owner's manual" approach is interesting because it centers on product promises rather than code structure — that's exactly the layer founders lose track of first.
Curious: does Stewie Reflect handle cases where AI-generated code introduces behavior that was never explicitly promised anywhere (implicit feature creep)? That seems like the hardest gap to surface.
That's a really good question.
One thing I've learned building this is that the manual reads the code, not my memory. So implicit feature creep actually surfaces pretty well — sometimes you genuinely get a "wait... when did I build that?" moment.
Where I try to be careful is intent. The repo can often prove that a behavior exists, but not why it exists. If the intent was never captured anywhere, I'd rather say "unknown" than make up a confident story.
Here's the sample manual if you're curious what that looks like in practice:
https://reflect.stewie.sh/#/manual
Comprehension debt is a real and very specific kind of pain that's becoming more common now that AI can generate working code faster than any of us can actually absorb it. The code runs fine. The founder just can't explain why anymore. This is a different problem than technical debt and it's interesting that nobody had a name for it until now. Six files and three integrations with no memory of choosing them is the kind of thing that feels harmless until you're trying to explain pricing logic to an investor and realize you can't.
Thanks, I appreciate that.
For me the scary part wasn't messy code. It was realizing I couldn't confidently answer simple product questions anymore without going back through the implementation.
The app still worked. My understanding just hadn't kept up.
"Comprehension debt" is honestly the part that stuck with me.
The product is interesting, but the idea itself immediately made sense.
One thing I've been learning while building Ashive is that it's surprisingly hard to tell whether something is a real problem or just a problem you've personally experienced enough times that it feels universal.
Out of curiosity, before building Stewie Reflect, did you see any evidence that other builders were feeling this pain too, or did you build it first and then start validating afterward?
Honest answer: it leaned build-first-then-validate, which I know is the riskier order. The pain was mine before it was anyone else’s, and I won’t dress that up.
What moved it from “my problem” to “maybe real” was seeing similar patterns in vibe-coding communities, but usually described as embarrassment or confusion rather than a direct feature request.
That was the signal for me. People don’t always ask for tools around problems they feel a bit embarrassed to admit.
The question you ended with is the right one. The comprehension debt pain is real — but "vibe coders who shipped with AI" is too broad to convert. The $19 unlocks will come from one specific moment: a founder about to touch billing or auth who is scared of what the AI actually wrote in there. That's a very different person from someone who just thinks it sounds useful. Worth figuring out where those people are signalling that fear before optimising anything else.
Yes, I think you’re right — thanks for pointing that out.
“AI-built products” is probably too broad. The real moment is when you’re about to touch something risky and suddenly realize you don’t fully trust your own understanding.
Billing and auth are actually where I first felt this in my own product, so that’s probably the sharper wedge: limits, upgrade logic, permissions, onboarding a new dev — much more urgent than “I should understand my codebase better.”
This is real, and I think there are two debts that get blended together: comprehension debt after shipping and budget/context debt while shipping.
I'm working on TokenBar, so I keep seeing the second one: people only notice AI sprawl after an agent has already burned through a huge context window or made a bunch of decisions they did not really inspect.
For Stewie, the sharpest positioning might be the moment right before a risky change: "before you touch billing, auth, limits, or upgrade logic, generate the manual and find the behaviors you can actually prove." That feels more urgent than general AI-built product anxiety, because it attaches to a scary task founders already avoid.
Yes, this is a helpful way to frame it — thanks.
“Before you touch the risky part” feels much sharper than general anxiety about AI-built code.
That’s the thing I’m trying to avoid too: a manual that just sounds confident. The useful version should say what behavior is actually supported, what is unclear, and where you should slow down before changing billing, auth, limits, or upgrade logic.
Comprehension debt is a sharp name for something that predates AI: the day you hire your second engineer you stop being able to explain half your own product, and AI just collapsed that from years to weeks. The reconstructed manual helps, but the durable fix is writing intended behavior down as a contract before you ship, not after. I have watched this exact gap surface in M&A diligence, where a founder who can't explain why their product behaves a certain way loses leverage fast.
Yes, I agree with this.
The durable fix is probably capturing intended behavior closer to the decision, not trying to reconstruct it months later.
I see the manual more as a recovery layer for existing codebases — useful when the product already exists and the context is scattered across code, commits, docs, chats, or someone’s memory.
That’s also why I’m open-sourcing the PBC spec separately. The manual is the after-the-fact view, but longer term I think the better flow is behavior contract first, manual second.
This resonates. The part that feels most real to me is not just forgetting the code, but forgetting the operational rule the code encoded.
Billing, limits, upgrade timing, retries, edge cases — those are product promises disguised as implementation details. AI can generate the implementation faster, but it usually does not force you to name the promise clearly.
I think a useful habit is to capture a tiny "behavior contract" before or right after shipping: input, expected behavior, exception, and why that choice was made. Even 5 lines would prevent a lot of future archaeology.
Your manual framing makes sense because it is closer to product memory than documentation.
Yes, this is very close to how I’m thinking about it.
“Product promises disguised as implementation details” is the part that keeps coming back for me. The code might say what happens, but unless the promise was named somewhere, you still end up doing archaeology later.
That’s also why I’m experimenting with the PBC spec separately — something small enough to capture the behavior before it disappears, but structured enough that a manual can be generated or checked against it later.
For context, this is the spec I’m starting from: https://github.com/stewie-sh/pbc-spec
"Comprehension debt" is a really good name for this. I think a lot of us have felt the technical-debt-vs-comprehension-debt split without having an actual phrase for it. Technical debt you can point at and say "yeah that's gross, I'll fix it later." This feels much worse because the code looks fine, passes review, works etc... you just can't reconstruct the reasoning anymore.
Exactly. Technical debt usually leaves clues.
Comprehension debt is harder because everything can look fine from the outside: tests pass, the feature works, users don’t complain. Then you come back later and realize the reasoning has disappeared.
That invisible part is what makes it feel more dangerous to me.
Comprehension debt is a pretty good name for it. What I keep noticing is that writing docs, comments, and commit messages is the first line of defense against it, but the switch from building to writing is brutal. You finish a feature, you know exactly why you made every decision, and then you've gotta type it all out before the context slips away. I built DictaFlow (dictaflow.io) partly because of that, hold a hotkey, say what you meant, release, and the explanation lands in your code or doc without breaking your flow. The typing bottleneck is real when you're trying to keep context at AI speed.
Yes, the timing is the hard part.
Right after shipping is when the reasoning is clearest, but also when you least want to stop and document it. Then a few weeks later the code is still there, but the intent is already fading.
I’m starting to think the capture step has to be almost frictionless, otherwise people just won’t do it.
This definitely resonates — “comprehension debt” is real, especially with AI-assisted builds. You can ship fast, but your mental model lags behind what the system actually does.
The billing example is a perfect one — those edge-case decisions (upgrades, limits, timing) are exactly where things break later because they’re hard to reconstruct.
I like the framing of a “manual” vs docs. The trust layer (what behavior is actually supported vs assumed) feels like the most valuable part here.
I’d say this isn’t just founder anxiety — it shows up anytime you revisit older parts of the product and hesitate because you’re not sure what you’ll find.
For me, it’s usually auth flows or edge-case logic I avoid touching for that exact reason.
Yes — “hesitate because you’re not sure what you’ll find” is exactly the feeling.
Auth flows and edge cases are a good example too. They often look fine until you need to change one small rule and realize you’re not sure which behavior is intentional, accidental, or only assumed.
That’s why the trust layer matters to me: not just summarizing the code, but separating what the repo clearly supports from what we’re guessing.
"Comprehension debt" is a great way to describe it.
AI has made building faster, but I've noticed the bottleneck shifting from implementation to understanding. A feature can work perfectly and still become expensive if nobody remembers why it behaves the way it does.
We've run into similar situations on AI-assisted projects at IT Path Solutions. The teams that scale best aren't necessarily the ones shipping the fastest, they're the ones preserving context and decisions as they build.
Yes, that shift from implementation to understanding is exactly what I’m feeling.
AI makes the build loop faster, but it doesn’t automatically preserve the reasoning behind each decision. So later the feature “works,” but the team has to rediscover what promise it actually encodes.
That context/decision layer is the part I think needs to be made much more explicit.
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.
Yes, cognitive load is a big part of it.
AI lets you move across more surfaces at once, but your understanding doesn’t scale the same way. You can ship five things in parallel, then later realize none of them are fully in your head.
That’s probably why focus + product memory matter more now, not less.
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?
Yes, I agree with this.
The hardest decisions to represent are the ones where the code shows the outcome, but not the tradeoff.
For example: upgrade timing, downgrade behavior, grace periods, usage limits, “soft block vs hard block,” admin overrides. The repo can usually show what happens. But it often cannot show why that choice was made unless the intent was captured somewhere.
That’s the gap I’m trying to make visible instead of smoothing over.
'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.
Yeah, I think that split is the key.
The manual is strongest at “what does this product actually do, and what can we prove from the repo?”
The “why was it built this way?” layer is harder. Some of that intent may exist in specs, commits, docs, or comments. But a lot of it originally lived in the builder’s mind. If that never got captured anywhere, the honest answer should be “unknown,” not a confident story.
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.
Yeah, this is exactly the thing I’m trying to figure out.
I know the pain is real for me. The open question is whether it becomes urgent enough for other builders at the moment they need to change something risky.
My current guess is that the wedge is not “AI-built products” in general, but specific scary moments: billing, auth, limits, onboarding a dev, or coming back to old code after a few months.
That's exactly why I asked.
Reading your reply, I don't think the hardest part is validating whether the pain exists anymore.
It's deciding what the current evidence actually justifies concluding about the product.
Happy to share the fuller thought if it's useful.
What's the best email to reach you on?
I'd love to hear it. You can reach me at [email protected].
Sent over what I was getting at.