running-a-proof-of-concept
Phase 3 (Proof of Concept) deep-dive playbook for an initiative shepherd. Deliverables: one or more PRs that demonstrate the recommended pattern in real Bitwarden code, Architecture Council review, and a draft ADR in the centralized contributing-docs repository (not per-repo). Time budget: 2–4 weeks, 40–80 hours of shepherd time. PoCs that stretch past 4 weeks usually signal either the wrong scope (too ambitious) or the wrong approach (the recommendation isn't working).
What the PoC Is For
Three things, in order:
- Prove the approach works in Bitwarden's real codebase — not in a sandbox, not on a clean repo, not in a hypothetical. Production-quality code on a representative slice.
- Surface the friction the assessment couldn't predict. Every approach looks good on paper. The PoC is where you discover that the chosen pattern needs a TypeScript interface refinement, or that the test infrastructure can't represent the new boundary, or that the receiving team's existing telemetry breaks under the new structure.
- Give the receiving teams something concrete to react to. A PoC PR is a far better basis for handoff than an architecture doc alone. Teams orient on code faster than on prose.
If the PoC doesn't accomplish all three, the next phase will pay for it.
Selecting the PoC Area
This is the highest-leverage decision in the phase. The funnel doc's guidance: representative but contained, ideally ~1–5 files or one module that demonstrates the key patterns.
How to choose: