/running-a-proof-of-concept

name: running-a-proof-of-concept
description: Phase 3 (Proof of Concept) deep-dive playbook — validates the Research recommendation in real Bitwarden code and drafts the ADR.
when_to_use: Use when Research has produced an approved recommendation and the shepherd is validating it in real code before Scoping. Triggers — "PoC time", "building the PoC", "drafting the ADR". Not for the High-Level Architecture Plan (use `scoping-and-handing-off-to-teams`) or cross-team coordination (use `coordinating-implementation-across-teams`).
allowed-tools: Skill, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_remote_links, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence_cql

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](https://github.com/bitwarden/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:

1. **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. 2. **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. 3. **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:

• **Pick an area that exercises the parts of the approach most likely to fail.** If the approach is async error handling, pick a service with non-trivial async paths. If it's a new state-management library, pick a feature with real state transitions.
• **Avoid the simplest possible case.** A PoC on a trivial slice proves nothing the assessment didn't already claim.
• **Avoid the worst possible case.** A PoC on the most pathological module of the codebase will fail for reasons that have nothing to do with the approach. You'll learn something, but not what you needed to learn.
• **Coordinate with the owning team's tech lead.** Their input on the right slice is usually decisive. They know which area is illustrative and which is a tarpit. They also know which area their team has spare capacity to host the PoC PR review on.

Once selected, identify a **point-of-contact on the owning team** (usually a senior engineer, sometimes the tech lead) who will pair with you or review your work. They are not adopting the work — they are your partner in surfacing where it doesn't fit.

This is also a good moment to consult `Skill(architecting-solutions)` in `bitwarden-delivery-tools` for the team-scope architectural constraints that will shape your PoC (security mindset, multi-client reality, V+/-2 compatibility, etc.). The PoC ships against those constraints from the start, not retrofitted.

Building the PoC

Framework / Foundation

If the approach requires shared scaffolding — middleware, base classes, type definitions, shared libraries — build it first. This is the reusable piece that broader rollout depends on. The framework itself is part of what the PoC is validating.

Two principles:

• **Production-quality.** Cut corners on scope, not on quality. The funnel doc is explicit: "don't cut corners — this tests whether the approach actually works." Corner-cut PoCs answer the question "could this work if everything were perfect?" — not the question you actually need to answer.
• **Match existing patterns where they exist.** New code that ignores established Bitwarden conventions will fail review for reasons that obscure whether the approach itself worked. Read first. Build alongside, not in opposition to, what's already there.

Example Implementation(s)

Implement 1–3 examples demonstrating the new pattern in the chosen area. Each example should be self-contained enough that a reviewer can see the pattern in action, but realistic enough that it tests real-world complexity. Examples from the funnel doc: migrate one API endpoint, one UI component, or one service module.

For each example, capture:

• **What worked.** The cases where the pattern fits cleanly.
• **What challenges emerged.** Edge cases, integration friction, places where the framework had to be adjusted, things that surprised you.
• **What would need to change for full rollout.** Sometimes the PoC reveals that the framework needs refactoring before scale-out; sometimes it reveals that the rollout itself needs phasing.

The PR(s)

• Mark "PoC" in the title if not intended for merge — the funnel doc allows either, but be explicit about intent.
• In the PR description, write the three points above (what worked, what cha