running-a-proof-of-concept

What this skill does

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-tech-lead` 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 challenges, what would change). The PR description is the most-read artifact of the PoC; teams will read it months after the PoC PR was opened.
- Link to the Architectural Assessment so reviewers have context for why the pattern looks the way it does.

## Architecture Council Walkthrough

The funnel doc strongly recommends presenting the PoC to [Architecture Council](https://bitwarden.atlassian.net/wiki/spaces/EN/pages/751698031) at this phase. Format:

- 15–30 minute walkthrough of the PoC findings.
- Add to an upcoming Council agenda — work with the Council facilitator on timing.
- Bring: the PoC PR(s), the assessment summary, your honest read on what worked and what didn't, your proposed direction (proceed / revise / return to Research / decline).
- Optional: have the owning team's point-of-contact attend. Their on-the-ground perspective often carries weight the shepherd's framing can't.

What the Council provides: pattern-level guidance, cross-initiative awareness (is this approach in conflict with something else underway?), validation of the proposed direction, and surface concerns about rollout.

What the Council does not provide: a green light independent of engineering leadership's go/no-go at the end of the phase. The Council recommends; leadership decides.

## Drafting the ADR

If the PoC validates the approach, draft an Architecture Decision Record following the [Bitwarden ADR template](https://contributing.bitwarden.com/architecture/adr/). ADRs live in the centralized [`bitwarden/contributing-docs`](https://github.com/bitwarden/contributing-docs) repository under `docs/architecture/adr/` (rendered at `contributing.bitwarden.com/architecture/adr/`). There is no per-repo ADR directory — Bitwarden's architectural decisions are intentionally centralized so they're discoverable across all codebases the decision touches.

Open a PR against `contributing-docs` with the new ADR file, numbered sequentially after the latest accepted ADR. Example for reference: [`0020-observability-with-opentelemetry.md`](https://github.com/bitwarden/contributing-docs/blob/main/docs/architecture/adr/0020-observability-with-opentelemetry.md).

The ADR is **not** the architecture plan — that comes in Scoping. The ADR is the decision artifact. Sections per the template:

- **Context and problem statement.** A self-contained summary; don't assume the reader has the assessment open.
- **Decision (chosen solution).** Specific. Name the pattern, library, or approach.
- **Alternatives considered.** From the assessment's 2–4 options. Brief — full trade-offs are in the assessment.
- **Rationale for decision.** Tie to the PoC findings, not just the assessment.
- **Consequences (positive and negative).** What changes for the codebase, the teams, operations, security posture. Negative consequences belong here — the ADR is honest, not promotional.
- **Status: Proposed.** It moves to "Accepted" during Phase 4 once leadership has committed.

The ADR is the durable artifact that survives the shepherd's departure. Six months from now, someone will hit a related decision and read this ADR to understand why the codebase is shaped the way it is. Write for that reader.

## Establish