You hired a team to build your product. They shipped it. The demo looked great. Everyone signed off.
Then the contract ended — and the knowledge left with them.
Six months later, a new team picks up the codebase. They open the repo and find code that works, but no record of why it works the way it does. No explanation of which behaviors are intentional product decisions and which are leftover workarounds. No way to tell what was confirmed by the client and what the previous team assumed.
This is the outsourcing handoff problem. And it costs more than most teams realize.
The knowledge gap no one budgets for
When you outsource product development, you're paying for two things: the code and the knowledge behind it.
You get the code. You almost never get the knowledge.
That's because product knowledge — the business rules, edge cases, design decisions, and "why we did it this way" context — lives in the previous team's heads. Some of it lands in Jira tickets or Confluence pages, but those go stale fast. Most of it never gets written down at all.
The result:
- The new team starts from zero. They read the code, but code tells you what — not why. They spend weeks reverse-engineering decisions that the previous team made in an afternoon.
- The client can't verify what was built. You approved the feature demos, but you can't check whether the business rules behind them match what you actually asked for. Did the 30-day trial window get implemented as a hard policy or a soft default? Nobody knows anymore.
- Assumptions compound. Each new team layers their own interpretation on top of the last team's assumptions. After two vendor transitions, the product's behavior has drifted from anyone's intent.
Why documentation doesn't solve this
The standard answer is "better documentation." Write more specs. Keep the wiki updated. Add comments to the code.
But documentation written from intent doesn't stay in sync with what's actually running. The team writes a spec before they build. Then they build something slightly different because of technical constraints. Then the spec never gets updated. Six months later, the spec says one thing, the code does another, and the client has no idea which is correct.
This is the fundamental problem: documentation describes what someone intended. It doesn't describe what the product actually does.
What a product contract changes
A product contract flips this around. Instead of starting from intent, it starts from the code.
Here's how it works in practice:
1. Analyze the codebase. Stewie reads your repository (read-only) and extracts candidate product behaviors — the business rules, policies, and logic that actually run in production. Each behavior comes with a confidence score and links to the source files that support it.
2. Confirm what's true. The client and the development team review the candidates together. "Is the 14-day refund window a confirmed policy?" "Does every API route enforce workspace tenancy?" Anyone can answer — no code knowledge required. You confirm what's right, reject what's wrong, and flag what's still undecided.
3. Produce a living spec. Confirmed behaviors become a product contract — plain Markdown files versioned in the repo. Every behavior links back to the code that supports it. When the code changes, you know exactly which product decisions are affected.
The key difference: this isn't documentation someone wrote and forgot about. It's a verified record of what the product does, confirmed by the people who care about it, and always in sync with the codebase.
Both sides win
For the client:
- You can verify what was actually built, not just what was demoed
- When you switch vendors, the new team inherits a verified product spec — not a stale wiki
- You retain product knowledge in the codebase, not in the vendor's heads
- You can onboard a new team in days instead of weeks
For the outsourcing team:
- You deliver more than code — you deliver a verified, transferable product record
- Handoff conversations become structured and evidence-based, not "let me walk you through the codebase"
- You reduce re-work from misunderstood requirements
- You differentiate from every other agency that just ships code and moves on
For the new team picking up the project:
- You see exactly what behaviors exist, which are confirmed, and which are still assumptions
- You don't have to reverse-engineer the previous team's decisions from code comments
- You know where the gaps are before you start building
The real cost of the handoff problem
Most teams budget for the vendor transition itself — the ramp-up time, the overlap period, the knowledge transfer sessions.
What they don't budget for is the ongoing cost of lost product knowledge. The bugs that happen because the new team didn't know about an edge case. The features that get rebuilt because nobody realized they already existed. The business rules that silently drift because there's no record of what was agreed.
A product contract doesn't eliminate the cost of switching teams. But it makes the transition a handoff instead of a restart.
The contract lives in the repo
One more thing that matters for outsourcing engagements: the product contract isn't trapped in another tool. It's plain Markdown files in your codebase — .pbc.md files that any team can read, any editor can open, and any future vendor can pick up.
The PBC spec is open source. Your product contract belongs to you, not to the tool that created it.
If you're managing an outsourced product and want to see what a product contract looks like for your codebase, request early access to Stewie.