// Draft engineering work breakdowns following the Bitwarden Tech Breakdown template. Use when starting a new tech breakdown, filling in the scope checklist, drafting specification child pages, capturing open questions, or moving the doc between status states (IN PLANNING / IN PROGRESS / PROPOSED / ACCEPTED / COMPLETE).
Coordinate cross-team review and signoff for a Bitwarden Tech Breakdown. Use when identifying affected teams, building the Part 3 signoff table, chasing signoffs to move from PROPOSED to ACCEPTED, or running the completion-communication checklist before COMPLETE.
Phase-by-phase guidance for participating in Bitwarden's Software Initiative Funnel. Covers ownership boundaries between shepherd and tech lead at each phase, how to run an epic breakdown after handoff, sizing and estimation, cross-team dependency tracking, and the escalation paths that protect team autonomy. Use when a team is about to receive an initiative epic, when participating in an Architectural Assessment or PoC, when preparing a team breakdown, or when surfacing concerns back to the shepherd or engineering leadership.
Primary-Owner playbook for shepherding a Technical Strategy Idea through Architecture's pre-funnel evaluation into the Software Initiative Funnel.
Phase 5 (Implementation) deep-dive playbook — shepherd coordinates teams executing the initiative across the support period, pulse check, retrospective, and closure.
Peer-Reviewer and portfolio-curator side of the TSI Shepherding Model — backlog stewardship, quarterly prioritization, funnel intake handoff.
Phase 3 (Proof of Concept) deep-dive playbook — validates the Research recommendation in real Bitwarden code and drafts the ADR.
| name | writing-tech-breakdowns |
| description | Draft engineering work breakdowns following the Bitwarden Tech Breakdown template. Use when starting a new tech breakdown, filling in the scope checklist, drafting specification child pages, capturing open questions, or moving the doc between status states (IN PLANNING / IN PROGRESS / PROPOSED / ACCEPTED / COMPLETE). |
| 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 |
Bitwarden's Tech Breakdown Template 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.
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:
This skill is written for whoever is at the keyboard. The activities are the same; the review path differs.
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:
Skill(coordinating-cross-team-breakdown)).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.
The template lives in the team's "Tech Breakdown" folder in Confluence. Setup steps from the template's preamble:
IN PLANNING).The header block is metadata that downstream readers — QA, refinement facilitators, other teams — rely on. Don't leave it blank.
The template defines six states. Move through them deliberately — status is how cross-team consumers know whether to engage:
Skill(coordinating-cross-team-breakdown) — once the doc reaches PROPOSED, the work shifts from authoring to coordination.Skill(coordinating-cross-team-breakdown)) has run.Two state-transition rules worth holding in mind:
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.
Three fields. Each is short but load-bearing.
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.
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.
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.
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:
If yes, list the tables, columns, and indexes affected. Then ask: will these changes need to be backwards compatible under Bitwarden's EDD (Evolutionary Database Design) model? Self-hosted instances cannot roll back migrations. If the change is backwards-incompatible, the rollout must be phased — make the phasing explicit here.
If yes, list the endpoints and contract changes. Then ask:
What components are touched, added, or changed? Then:
If the work touches the SDK, ask all four:
List the services. If touching pre-existing TypeScript services, ask whether the work should include migrating to a high-level SDK method rather than extending the TypeScript service. Don't extend without weighing this — it's how SDK adoption stalls.
Is this feature supported on Self-Hosted, Cloud, or both? Self-hosted has constraints (no rollback for DB migrations, longer upgrade lag, no centralized infrastructure to lean on) that change the design.
Will this feature be feature-flagged, or live on a long-lived feature branch? If flagged, where is the flag enforced — server-side, client-side, both? Which UI surfaces and services are gated by it? Long-lived feature branches are usually a smell; surface them so the team can decide whether the change is really shaped right.
Answer all three:
Skill(bitwarden-security-context) (in the bitwarden-security-engineer plugin).Skill(threat-modeling) (in the bitwarden-security-engineer plugin) is the source for definition format.What testing is required beyond the standard unit/integration coverage? Cross-platform tests, performance tests, security tests, load tests, manual QA flows. Note who runs each — the team, QA, security, another team.
What tech debt could be paid off opportunistically while this work is in progress? Be selective — pulling unrelated cleanup into the scope is how breakdowns balloon. The right answer is often "none, but document candidates for future work."
Does the solution need different behavior in developer environments — different defaults, mock backends, separate config? Note them so the team isn't surprised when local-vs-prod parity breaks.
Larger breakdowns produce one or more child pages — specification documents that go deeper than the breakdown can. Each child page covers one major component or decision area: an API contract, a data schema, a UI component API, a cryptographic scheme.
Link each artifact in Part 4's table. For each, verify before the breakdown moves to PROPOSED:
Skill(coordinating-cross-team-breakdown) — Part 4 child pages often need their own per-team review before the parent breakdown can move to ACCEPTED.If the breakdown is small enough that no child pages are needed, say so explicitly: "Specification is contained in Part 2 above; no separate artifacts required." Don't leave Part 4 silently empty.
Track every unresolved question with an owner and (ideally) a target resolution date. Open questions are not a sign of an incomplete breakdown — they're the explicit acknowledgment of what the team doesn't yet know. Hidden assumptions are the failure mode; tracked questions are healthy.
Move questions to closed (or delete them, with the resolution captured in Parts 1–4 as appropriate) as they're answered. A breakdown shouldn't reach ACCEPTED with material questions still open — if a question is blocking, treat it as a blocker and don't move to PROPOSED.
This block exists for Claude (and future engineers using Claude) coming back to the breakdown later. Populate it explicitly:
<feature>, owned by <team>, currently at <status>.A populated AI Context block is what makes the breakdown useful in future Claude conversations. Skipping it is a tax on every future read.
Once Parts 1, 2, 4, and 5 are complete and the team has reviewed internally, set status to PROPOSED. Then invoke Skill(coordinating-cross-team-breakdown) — the work shifts from authoring (this skill) to cross-team coordination (the companion skill). The companion skill owns:
The state machine lives in this skill; the cross-team workflow lives in the companion. They compose by cross-reference, not auto-invocation.
Skill(navigating-the-initiative-funnel) when an initiative exists is the most common upstream error.2920349776) — canonical. Fetch via get_confluence_page for the full template, the literal field labels, and the latest status definitions.Skill(navigating-the-initiative-funnel) — load-bearing when the breakdown sits under a BW Initiative; provides the shepherd, sibling-team, and architecture-plan context that feeds Parts 1, 2, 3. Skill(coordinating-cross-team-breakdown) — Part 3 signoffs, cross-team checklist, and the completion-communication workflow that closes the breakdown. Skill(architecting-solutions) (in the bitwarden-tech-lead plugin) — the architectural-judgment lens to apply through Part 2.