May 31, 2025
So I went on this hacking jag and I was starting to drink the Flavor Aid…
You know that feeling when you’re about to go on stage and you start to wonder whether your act is really as good as your mom told you? That’s me, preparing to demo Piper Morgan to my colleagues at Kind Systems.
The prototype was “working.” It could draft GitHub tickets. It had a web interface. It even had context levels — four hierarchical levels of context that I worried were a little too concrete but also kind of made sense?
Time to write up the documentation and prepare some slides. How hard could it be? Claude can even make a web-native HTML slide show for the demo for me.
The documentation exercise that became an intervention
First task: write up what Piper Morgan could actually do. Not what it might do, or what it would do “with a few more tweaks,” but what it actually, demonstrably did right then.
Claude (Sonnet 4, in its infinite enthusiasm) helped me create comprehensive documentation. Project report, technical specs, requirements docs — the works. Reading the first draft was like looking in a funhouse mirror:
“The system seamlessly integrates organizational knowledge across multiple context levels…”
Did it though? Did it seamlessly do anything?
“Production-ready architecture with microservices design…”
I mean, technically it had services. Micro? Sure, they were small. Production-ready? Well, it hadn’t caught fire yet.
The docs literally claimed the project was not only production ready but also that it was time for engineers to drop what they were doing and help out with it. This was so not true. I didn’t want to even accidentally imply it, especially when another slide was hinting that we could easily eliminate PM and engineer jobs with all this amazing efficiency. Very very not true!
The reality check
After reading through these documents that made Piper Morgan sound like it was ready to replace half of Atlassian’s product suite, I had to pump the brakes.
“Can we make these more realistic and less hype-y?”
What came back was documentation so conservative it made my prototype sound like a middle school science fair project. We’d swung from “revolutionary AI platform” to “experimental prototype with significant limitations (may contain nuts).”
The truth, as always, was somewhere in the middle. But that exercise of writing honest documentation is when the cracks started to show a bit more clearly.
The four levels of context (that weren’t)
Let me tell you about my beautiful context hierarchy:
- Product management craft knowledge
- Client/partner information
- Project/product specifics
- Individual task details
Elegant, right? Except here’s what actually happened when you uploaded a document:
“Is this about the client or the project?”
“Well, it mentions both…”
“I’ll just put it in… both?”
“Wait, now it’s showing up in task context too.”
“Why is the PM craft knowledge talking about our specific client?”
The context levels weren’t levels. They were more like… context soup. With croutons of confusion. Poor Piper was writing me tickets that mixed a hypothetical client project with its own development!
The file upload feature that broke wverything
But the real moment of truth came when I added file uploads. Seemed simple enough — let people upload PDFs and Word docs, extract the text, make it searchable. What could go wrong?
Everything. Everything could go wrong.
First, the UI needed to know which context level (remember the soup?) to assign the upload to. Then it needed client and project selection. Then we needed to handle multiple file formats. Then permissions (wait, should project docs be visible at the client level?). Then…
I found myself writing code like this:
if context_level == "client" and project_id:
# Wait, this makes no sense
context_level = "project" # Force it?
elif context_level == "project" and not project_id:
# This is even worse
raise ValueError("But the UI shouldn't allow this?")Anyone who has worked with software has experience feature creep, and rabbit holes, and band-aids on top of band-aids. It’s a familiar smell.
The demo prep that became a reckoning
As I looked at the original cringe slides and the more morose update, I started feeling unsure about what my story way:
Slide 3: “Current Capabilities”
- Draft GitHub tickets ✓ (sort of)
- Analyze existing tickets ✓ (basically grep with extra steps)
- Maintain context ✓ (if you squint)
- Learn from feedback ✗ (TODO: figure out what this means)
Slide 4: “Architecture Overview” [Frantically drawing boxes and arrows to make spaghetti code look intentional]
Slide 5: “Demo” [Practicing the exact sequence that doesn’t trigger the known bugs]
My favorite “feature” was when I asked Piper to analyze a list of issues and write up github tickets for them based on a template and it wrote me a github ticket outline the steps one would take to analyze a list of issues and write up github tickets for them based on a template.
The Moment of Clarity
It hit me while writing the “Known Limitations” slide. The list kept growing:
- Context levels blur together
- File uploads may assign to wrong level
- Client selection affects project visibility (sometimes)
- Learning system not implemented (but we track things!)
- GitHub integration hard-coded
- Can’t actually tell the difference between a bug and a feature request
- May occasionally suggest you assign tickets to people who don’t exist
At some point, you have to ask: Is this a prototype with limitations, or just a very elaborate way to generate GitHub tickets with extra steps?
The demo that never happened
I never gave that demo. I did share what I was working on what I’d been learning (a lot! it turns out). But I realized I wasn’t really going to be demo-ing a prototype. I would be demo-ing technical debt with a web interface.
The real Piper Morgan — the one that could actually help PMs work smarter — was trapped inside this tangle of hasty decisions and bolted-on features. It deserved better architecture. It deserved domain-driven design. It deserved not to be held together with string and good intentions.
What I learned about prototypes
Prototypes are like houseguests — delightful at first, problematic if they overstay their welcome. The moment you start adding “just one more feature” to make it “demo-ready,” you’re no longer prototyping. You’re building. And if you’re building on a foundation of “let’s just get this working,” you’re building on sand.
The documentation exercise didn’t kill my prototype. It performed an autopsy on something that was already dead — I just hadn’t noticed yet because it was still moving.
And, you know, it’s fine
Here’s the thing: This was the best possible outcome. That failed demo prep taught me more about what Piper Morgan needed to be than weeks of successful prototyping. Every limitation I documented became a requirement. Every architectural flaw helped inform a design principle for the MVP (no spoilers!).
The beginning of the real build
That night, after abandoning my slides and accepting reality, I made a decision. Piper Morgan deserved to be built right. Domain-first. Properly architected. With context levels that actually meant something and file uploads that didn’t cause existential crises.
Time to stop prototyping and start building.