Most product teams have a quiet problem they don’t talk about enough:
Everyone is working from a slightly different version of the product.
Sales is pitching what they think exists.
Product is planning what should exist.
Engineering is building what was specified—weeks or months ago.
And then AI shows up, and suddenly that ambiguity isn’t just inefficient—it’s a liability.
This is the story of how we tackled that problem at TellGovernment by evolving from a simple AI-generated document into a structured, living product knowledge base—and why we think this pattern will become standard.
Where This Started: One Prompt, One File
This didn’t begin as a grand system.
It started with an engineer using Codex and a very practical prompt:
“I want to create a summary of the purpose of TellGovernment.com and all of it’s features in a succinct document that a human or AI could consume. Let’s make this a top level document called functionality.md. This document will mostly be consumed by product and sales who will use it to inform themselves of what they should be doing next”
That generated functionality.md.
And honestly—it was good.
It captured:
- What TellGovernment is (a platform for sending physical postcards to elected officials)
- Who it serves (constituents, organizations, widget customers, API partners)
- The core flow (address → official → postcard → payment → fulfillment)
- Key features (campaigns, tokens, widgets, APIs)
- Guardrails (what not to promise)
It immediately became useful:
- Sales could align messaging
- Product could sanity-check roadmap decisions
- Engineers had context for why things existed
But it had a limitation.
It was still just… a document.
The Realization: Documents Don’t Scale, Systems Do
As soon as we started using functionality.md in real workflows, the cracks showed:
- You couldn’t query it (“what features depend on tokens?”)
- You couldn’t easily update specific parts without re-reading everything
- AI could read it—but not reliably reason across it
- It drifted unless someone explicitly remembered to maintain it
It was a great artifact, but not a great system.
And once AI became part of our workflow, that gap mattered a lot more.
Because AI doesn’t just read—it operates.
The Evolution: From Markdown to product.json
So we made a shift:
We converted the document into a structured JSON artifact:
knowledge/product.jsonInstead of paragraphs, we now have:
- Product definition
- Personas
- Core flows
- Feature modules
- Dependencies
- Monetization model
- Constraints (what we explicitly don’t promise)
This changed the nature of the artifact completely.
Now it’s not just something you read—it’s something you can:
- Traverse
- Validate
- Extend
- Use programmatically
And importantly:
Engineers and AI agents can update it as part of normal work.
Why This Matters (Across Teams)
For Product
You finally get a single, structured map of the product.
Not slides. Not scattered docs. Not tribal knowledge.
You can answer:
- What actually exists today?
- What depends on what?
- Where are we adding complexity vs strengthening the core?
For Sales
You reduce one of the biggest hidden risks: overpromising.
The original functionality.md already included a “what not to promise” section. Encoding that into the system means:
- Messaging stays grounded
- New reps ramp faster
- Fewer awkward “that’s not actually how it works” moments
For Engineering
This is where it gets interesting.
You now have a product-layer abstraction that sits above specs.
- Specs (
specs/...) = how things work product.json= what exists and why
That separation is powerful.
It means:
- You can refactor implementation without losing product clarity
- You can reason about impact across features
- AI agents can navigate the system with context
Being Honest About AI’s Role
AI didn’t replace thinking here—it accelerated the first 60%.
- Codex generated the initial
functionality.md - That gave us a fast, coherent baseline
- Humans validated, corrected, and structured it
- Then we transformed it into something durable
Without AI, this probably wouldn’t have been prioritized.
With AI, it became obvious:
If machines are going to help build the product, they need a clean, structured understanding of it.
This is less about “AI writing docs” and more about:
designing systems that both humans and AI can operate on.
Governance: Making It Real (Not Just Another File)
The key decision wasn’t creating product.json.
It was deciding who owns it and when it changes.
We’re treating it as part of the system, not documentation.
That means:
- It lives in the repo (
knowledge/product.json) - It evolves with product changes
- It’s referenced in our internal “constitution”
A simple rule we’re adopting:
If a change affects product behavior, packaging, or claims—it must update
product.json.
That’s what turns this from “nice idea” into actual leverage.
What We Expect Next
This is the beginning, not the end.
Here’s where this goes:
1. AI-Native Product Reasoning
Agents can:
- Understand the product surface area
- Avoid suggesting impossible features
- Navigate dependencies intelligently
2. Better Roadmap Decisions
You can evaluate:
- Does this deepen the core flow?
- Does it expand a module (Premier, widget, API)?
- Or does it introduce unnecessary surface area?
3. Tighter Sales–Product Alignment
Instead of “what do we sell?” being interpretive, it becomes:
- Explicit
- Versioned
- Shared
4. Living Product Intelligence
Eventually this connects to:
- Specs (
specs/...) - Metrics
- Ownership
- APIs
At that point, you don’t just have documentation.
You have a model of your product.
The Bigger Shift
Most teams still treat product knowledge as:
- Slides
- Notion pages
- Docs that drift
We’re moving toward:
Product as structured data
Because once you do that:
- Humans align faster
- AI becomes useful instead of risky
- The system starts to explain itself
Final Thought
This didn’t start as a big strategic initiative.
It started with an engineer asking:
“Can we just summarize what this thing actually does?”
That question turned out to be more important than it looked.
Because once you can answer it clearly—and structurally—you unlock a very different way of building.
And if you’re planning to work alongside AI, you’re going to need that clarity anyway.
Leave a Reply