“The Lost Weekend” Part 2 of 4, when “it works on my machine” isn’t enough
May 30, later that day
Part 1 of this story crashed my browser. Which feels perfect for a weekend where everything was slightly broken, including my memory.
What I do remember: six documents in one marathon session. After taking the project to Gemini, I told it to just go ahead and write me a set of specs and docs. This was my first experiment in the circular pattern of writing code from vibes, extracting specs from code, revising the specs and using it to develop more code.
Lather, rinse repeat.
The unglamorous prep work
Why six documents? I didn’t have much to demo yet and I needed a way to show professionals what I was working on and I needed a benchmark. Here is what we had so far:
- PM Agent Project One-Pager: Problem statement and business value
- Project Report for Engineers: Technical architecture and achievements
- Requirements Document v0.1: Formal functional specifications
- Technical Specification v0.1: Implementation details and data flows
- Product Roadmap: Strategic “Now/Next/Later” planning
- Prioritized Backlog: Actionable tasks with dependencies
Each document demanded a different brain. Different audience. Different level of technical detail.
From prototype to demo
The hardest part wasn’t the writing — it was the thinking. Stepping outside the builder mindset to see the system through other eyes.
Engineers need architecture diagrams. Product managers need requirements. Executives need ROI calculations. Each group speaks a different language, and they all need to understand the same system.
Working solo with language models is seductive. You can forget that you’re the only human in the loop and everything else is a calculated refraction of what you put into it (plus or minus the rest of the scrapeable internet). Showing what you’re doing to other people is an important reality check.
The memory hole lesson
Here’s what’s funny about Part 1 being lost. There’s a tiny piece of the lost weekend that will always be out of reach from its own memory. I can interpolate. That’s what these machines do all day. I have the before and after, the what came next. I know what it must have been, but I can’t prove it. I’m guessing. I’m just as much of a fabulist as these LLMs.
Also, hey. It’s the perfect metaphor for prototype development. You build in a frenzy, browser crashes eat your work, and you’re left reconstructing what happened from fragments.
Just like documentation, really. You patch together the story from commit logs, chat transcripts, and whatever survived the chaos.
The exhaustion of translation
Building code is one kind of thinking. Explaining code is entirely different. That first Saturday afternoon (two days in and I was working weekend on a side project!?) was when I realized that sometimes the best coding is writing docs about your code.
Not because documentation is more important than functionality, but because the act of explanation forces clarity you didn’t know you were missing. Also, when the code is being written by machines, documentation is governance, architecture, steering.
The prototype worked (barely, for some definitons of “worked”). But until it was documented, it was just an interesting toy.
Documentation also turns it into something other people could use, understand, and improve.
The demo that would change everything
Looking back, this wasn’t really about the demo. It was about the transition from individual tool to organizational capability. We’ve already written about “The Demo That Killed The Prototype” so we know where that story is going but this is before the demo, when we were still trying to figure out what the what was.
Bottom line: The prototype was built for me. The documentation was built for everyone else.
That six-document marathon was the bridge between “I built something cool” and “we have a product.”