writing-tech-breakdowns

What this skill does

Bitwarden's [Tech Breakdown Template](https://bitwarden.atlassian.net/wiki/spaces/EN/pages/2920349776) is the standard artifact a team produces before implementation begins on a non-trivial change. It captures the technical design — what's being built, what it touches, what alternatives were considered, what the cross-team impact is — at the level of fidelity another engineer or another team can act on. This skill is the working playbook for drafting the engineering content (Parts 1, 2, 4, 5, 6) and managing the document's status lifecycle. Part 3 (cross-team signoffs) and the completion-communication checklist live in the companion skill `Skill(coordinating-cross-team-breakdown)`.

When the canonical template structure is needed, fetch page `2920349776` via `get_confluence_page`; this document is the operating summary, not the source of truth.

## Who Drafts a Tech Breakdown

The tech lead traditionally owns the breakdown for the team's work, but software engineers contribute heavily to or fully draft sections. Two common ownership patterns:

- **Engineer-led:** an engineer picks up a piece of scope and drafts the breakdown end-to-end, with the tech lead reviewing before it moves to PROPOSED.
- **Tech-lead-led:** the tech lead frames the problem, populates Parts 1 and 2 with the team, and divides Part 4 specification artifacts among engineers.

This skill is written for whoever is at the keyboard. The activities are the same; the review path differs.

## Before You Start: Orient on the Initiative

If the change exists under a larger BW Initiative — an epic the team received from a shepherd through the Software Initiative Funnel — **run `Skill(navigating-the-initiative-funnel)` first**. It surfaces the context that feeds multiple parts of the breakdown:

- The originating initiative epic, its architecture plan, and the PoC PRs the shepherd produced — these are the source material for Parts 1, 2, and 4.
- The shepherd's stated success criteria and constraints — Part 2 questions get answered against these, not against guesses.
- Sibling teams' epics under the same initiative — these populate the "Related breakdowns" link in Part 1 and seed Part 3's signoff table (handled in `Skill(coordinating-cross-team-breakdown)`).
- The shepherd themselves — escalate ambiguous scope or cross-team interface questions to them rather than resolving unilaterally.

If no initiative exists — the work is purely team-scoped — skip this step and note it explicitly in Part 1 ("not part of an active initiative"). A breakdown without an initiative is fine; a breakdown drafted in a vacuum when an initiative exists is not.

## Starting a New Breakdown

The template lives in the team's "Tech Breakdown" folder in Confluence. Setup steps from the template's preamble:

1. **Copy the template** into the team's folder. Don't edit the template page directly.
2. **Switch permissions to view-only** via the lock icon in the upper right. Tech breakdowns are reference artifacts after they're ACCEPTED — they should not be silently re-edited.
3. **Delete the template checklist** at the top once the copy is made.
4. **Fill the header block:** Owner (the human accountable, not a team), Deadline (when the breakdown itself is expected to be done — not when implementation ships), Status (start at `IN PLANNING`).

The header block is metadata that downstream readers — QA, refinement facilitators, other teams — rely on. Don't leave it blank.

## The Status Lifecycle

The template defines six states. Move through them deliberately — status is how cross-team consumers know whether to engage:

- **IN PLANNING** — expected, but not actively being worked on. Use when the breakdown is committed to but the team hasn't started drafting. Don't sit here for long; it's the weakest signal of intent.
- **IN PROGRESS** — actively being drafted. Parts 1, 2, and any Part 4 child pages are being filled in. Cross-team review is not yet appropriate.
- **PROPOSED** — ready for review. Parts 1, 2, 4, 5 are complete; Part 3's signoff table identifies who needs to review. **This is the gate to `Skill(coordinating-cross-team-breakdown)`** — once the doc reaches PROPOSED, the work shifts from authoring to coordination.
- **ACCEPTED** — all affected teams have signed off via Part 3. The breakdown is now the agreed-on technical design. The team can begin implementation. Implementation should not begin before this state when cross-team interfaces are involved.
- **COMPLETE** — implementation has shipped and the completion-communication checklist (handled in `Skill(coordinating-cross-team-breakdown)`) has run.
- **REJECTED** — review surfaced incompatibilities or blockers that can't be resolved. The breakdown is preserved as historical record; a new breakdown supersedes it.

Two state-transition rules worth holding in mind:

- **Don't skip PROPOSED.** Moving straight from IN PROGRESS to ACCEPTED hides the cross-team review work and produces signoffs that read like rubber stamps.
- **Don't reopen ACCEPTED for material changes.** If the design needs to change after teams have signed off, either supersede with a new breakdown or push the change back to PROPOSED and re-run the relevant signoffs. Silent edits after ACCEPTED defeat the point of the artifact.

If the lifecycle on the canonical page differs from what's described here, the canonical page wins — fetch it via `get_confluence_page` on page `2920349776`.

## Part 1: The Problem Overview

Three fields. Each is short but load-bearing.

### Feature description and overview

Link the Jira epic or story, the Product feature document, and the design files. Then write one or two paragraphs framing the problem in the team's voice — what's being built, who it's for, why now. **Do not paste the Product spec.** A breakdown is a technical document; the problem section is the bridge from Product intent to engineering work, not a copy of the requirements.

If the Product feature document is incomplete or contradicts what the team has been told, surface it here as an open question (Part 5) rather than guessing. Ambiguous Product intent is the single biggest source of churn in breakdowns.

### Related breakdowns

If this work is part of a larger initiative — almost always when a shepherd is involved — link sibling teams' breakdowns here. Use `Skill(navigating-the-initiative-funnel)` to find them, or ask the shepherd directly. Cross-linking matters: a reader landing on this breakdown should be able to trace back to the initiative and across to peer-team work in two clicks.

For team-scoped work with no parent initiative, write "Not part of an active initiative" rather than leaving the field blank.

### Are there alternative solutions that could accomplish the Product requirements with less effort?

Answer honestly. The point of this field is to force the question — "could we satisfy Product with a smaller change?" — not to produce a long alternatives table. One or two sentences is usually right. If a smaller approach exists and is being rejected, name the reason.

**Distinction from Part 4:** Part 1's alternatives are "could we not build this in this shape at all?" Part 4's per-artifact alternatives are "given we're building this, which designs did we reject for each component?" Don't conflate them.

## Part 2: The Breakdown Scope Checklist

This is the heart of the breakdown — a systematic survey of what the change touches. Each question has a yes/no flavor, but the value is in the follow-ups: when "yes," what's the actual scope, and what does it imply for compatibility, security, and other teams.

Apply architectural judgment as you answer. **Use `Skill(architecting-solutions)` (in the `bitwarden-tech-lead` plugin) as the lens** — blast-radius assessment, dual-data-access parity, V±2 client compatibility, multi-client reality. Don't re-derive those principles here; reach for the skill.

The canonical checklist on page `2920349776` is authoritative. Here is the operating summary:

### D