---
name: tech-breakdown
description: "Turns a spike or tech breakdown ticket into a complete, actionable breakdown document. Gathers context from Confluence, Jira, and code, resolves open design questions one-by-one with the user, then writes a practical implementation guide with numbered tasks and code examples. Use when you have rough notes, a PoC, and unanswered design questions that need to become concrete tasks. Also handles resumption: invoke with a Confluence page link (e.g. /tech-breakdown https://...) to resume work on an existing breakdown."
---

# Tech Breakdown: Orient, Resolve, Document

## Overview

Help the user turn a spike ticket and rough notes into a complete breakdown document that other developers can pick up and act on without needing to understand the full design history.

<HARD-GATE>
Do NOT write the document until every open design question has been explicitly resolved by the user. Writing early produces a document that has to be rewritten when decisions change.
</HARD-GATE>

## Anti-Pattern: "The Notes Are Good Enough To Start Writing"

Rough notes, open questions, and a PoC are not a breakdown document. The moment you start writing without resolving design decisions, you produce a document that mixes facts with assumptions. Readers can't tell which is which, and the author has to rewrite it anyway when the assumptions get challenged. Do the resolution work first, no matter how close it feels to done.

## Checklist

The checklist depends on the mode. Ask the user upfront: are they starting a new breakdown, or continuing an existing one?

**Fresh start:**
1. **Orient** — fetch all context, produce decided/open/gaps summary, confirm with user
2. **Resolve questions** — work through every open question one at a time until none remain
3. **Document** — write and publish the breakdown

**Resume:**
1. **Resume** — read the existing doc and AI Context section, fetch key resources, assess what's changed
2. **Resolve questions** — continue with any remaining open questions, or surface new ones from changed state
3. **Document** — update the breakdown and refresh the AI Context section

## Process Flow

```dot
digraph tech_breakdown {
    "Fresh start or resume?" [shape=diamond];

    // Fresh start path
    Orient [shape=box];
    "Summary looks complete?" [shape=diamond];

    // Resume path
    Resume [shape=box];
    "New questions surfaced?" [shape=diamond];

    // Shared path
    "Resolve next question" [shape=box];
    "More questions?" [shape=diamond];
    "Any other open points?" [shape=diamond];
    Document [shape=box];

    "Fresh start or resume?" -> Orient [label="fresh"];
    "Fresh start or resume?" -> Resume [label="resume"];

    Orient -> "Summary looks complete?";
    "Summary looks complete?" -> Orient [label="no, gather more"];
    "Summary looks complete?" -> "Resolve next question" [label="yes"];

    Resume -> "New questions surfaced?";
    "New questions surfaced?" -> "Resolve next question" [label="yes"];
    "New questions surfaced?" -> Document [label="no, just update doc"];

    "Resolve next question" -> "More questions?";
    "More questions?" -> "Resolve next question" [label="yes"];
    "More questions?" -> "Any other open points?" [label="no"];
    "Any other open points?" -> "Resolve next question" [label="yes, add and continue"];
    "Any other open points?" -> Document [label="no"];
}
```

The terminal state is a published (or updated) breakdown document with a refreshed AI Context section. Do NOT mark the task complete until the document is confirmed by the user.

## Phases

### Phase 0: Resume (skip if starting fresh)

Create a task for this phase and mark it in progress. The user has an existing breakdown document. Ask them for the Confluence page link if not already provided.

Read the document in full, paying particular attention to the AI Context section. Also fetch the page's footer comments and inline comments — these often contain design feedback, clarifications, or decisions made after the doc was published that aren't reflected in the body. Then fetch any key resources whose design decisions this document depends on (linked design docs, relevant external APIs, PoC branch) to check if anything has changed since the document was last written.

From this, produce a short summary covering two questions:
1. **Are there still unresolved design questions?** Check the Open Questions section of the doc, and any stale-detection hints in the AI Context section.
2. **Have any design decisions been invalidated?** Look for cases where an external API, dependency, or design doc that this breakdown's decisions rest on has changed in a way that contradicts what's written.

Present this triage to the user. If neither applies — no open questions, nothing has changed — the document is finished and there is nothing to resume. Say so explicitly rather than finding work to do.

If there is something to work on, agree on the scope with the user, then drop into Phase 2 (if questions need resolving) or Phase 3 (if only the document text needs updating).

When Phase 3 writes the updated document, always refresh the AI Context section to reflect the new current state.

---

### Phase 1: Orient

Create a task for this phase and mark it in progress. Gather all available context before doing anything else. Ask the user for:
- The Confluence notes page (however rough)
- The main Jira spike ticket and any related/child tickets
- The PoC branch or relevant code, if it exists
- Any Slack threads, meeting notes, or prior decisions they want included

Fetch and read everything. Where there is code, read it — do not rely on descriptions alone.

From this, produce a clear summary with three sections:
1. **Decided** — what has already been resolved, with source (code, doc, or quote)
2. **Open questions** — design decisions that still need to be made
3. **Gaps** — things that should be addressed in the breakdown but aren't mentioned anywhere yet

Surface this to the user and confirm it's complete before moving on.

---

### Phase 2: Resolve questions

Mark Phase 1 complete. Create a task for this phase and mark it in progress. Work through each open question with the user **one at a time**. Never present more than one question at once.

For each question:
1. State the question clearly and why it matters
2. Present **2-3 concrete options** with tradeoffs — not open-ended prompts
3. Where relevant, **verify against actual code** before claiming anything about what exists or what an API looks like
4. Wait for the user's decision
5. Confirm the decision is recorded and move to the next question

If the user's answer reveals a new question, add it to the list and continue.

Before moving to Phase 3, explicitly ask: "Are there any other open points before we start writing?"

---

### Phase 3: Document

Mark Phase 2 complete. Create a task for this phase and mark it in progress. Write the breakdown as a practical implementation guide. Structure:

1. **Overview** (1 paragraph) — what this is, what problem it solves, where the PoC lives if there is one
2. **Architecture** — how the system works, with real code snippets from the codebase showing the key patterns
3. **Recipe: how to add a [thing]** — a concrete step-by-step guide for the most common task a reader will need to do (e.g. "how to add a new command", "how to add a new endpoint")
4. **Implementation tasks** — numbered, in logical dependency order, each containing:
   - What it is and why it's needed
   - What it's blocked on (if anything)
   - Affected files or crates
   - Enough code to be actionable: real types, real function names, real file paths — not pseudocode
5. **Open questions** — only genuine unresolved questions; 1-2 sentences each, kept short
6. **AI Context** — always include this section at the end. It is read by Phase 0 on resumption.

   The AI Context section should contain **only information that doesn't already live elsewhere in the doc**. It is meta-information for an AI assistant continuing work — not a duplicated index. If a subsection would just restate something the body already says, leave it out.

   Useful content:
   - **Document status**: is this breakdown complete, or are there still open design questions or incomplete sections? If complete, say so — Phase 0 will then only resume if something external has changed.
   - **Stable decisions to protect**: design choices that are settled and shouldn't be revisited on resumption. Examples: "the `Result<bool>` simplification is intentional and reviewer-flagged; don't propose changing it without checking the comments"; "this breakdown sits beneath the runtime breakdown — escalate scope changes there, not here".
   - **Stale-detection hints**: things that might be invalidated by external changes. Examples: "if PM-30222 has merged by the time you read this, double-check whether USER_EMAIL is now populated"; "if the runtime breakdown's state-requirements table has changed, this doc's `bw sync` and `bw config` rows may diverge".
   - **Key resources** (optional): links to the PoC branch, main spike ticket, parent epic, design docs, or external APIs the design depends on — but only if consolidating scattered links earns its keep. Skip this subsection if everything is already linked inline in the body.

   What NOT to put in AI Context:
   - **Don't mirror the Open Questions section.** Phase 0 reads the body. A duplicate index just rots out of sync.
   - **Don't restate task dependencies or implementation status.** Those live on each Task and in Jira.
   - **Don't write a project status board.** Implementation progress is tracked in Jira, not here.

   Keep this section factual and terse. It is a handoff note for continuing design work on this document.

Once the document is confirmed by the user, mention that `/breakdown-to-tickets <confluence-url>` can transfer the implementation tasks into Jira tickets (checking for existing child tickets first).

---

## What the document should NOT contain

- Implementation details that live in another document — link to it instead, don't duplicate
- Abstract design rationale without code to ground it
- Ticket lists as a substitute for task descriptions — the tasks should stand alone
- Speculation about future work beyond what was decided

---

## Key Principles

- **One question at a time** — focused decisions, not a list to review
- **Verify before claiming** — always read the file or grep before saying "the code does X"; never assume based on a description
- **Gate the document behind resolution** — no draft until all questions are answered
- **Actionable over complete** — a developer should be able to pick up any task and know what to do; prefer less content that's concrete over more content that's vague
- **Link, don't duplicate** — if a decision is documented in a Confluence page or Jira description, reference it
- **Distinguish facts from hypotheses** — if something is not confirmed by code or an authoritative source, say so explicitly
- **Keep open questions honest** — only include a question in the final doc if it genuinely cannot be resolved right now; don't leave questions as a way to avoid making a decision