Design Handoff

Design Handoff

One invariant, everything else negotiated. The invariant: the artefact this skill leaves behind must let a future session recover the full approved design on its own, which means one parent, a ticket or a document, carrying the design in full in its own body. The negotiated part is every structural choice around that parent: how many tickets, whether they group, whether the work needs one parent or several. Those shapes are read off the design and settled with the user, never imposed from a fixed hierarchy.

Preconditions

An approved design exists in conversation context: settled with the user and explicitly approved, recovered from an existing artefact, or carried by a specification the user has pointed to as approved. A design you have inferred from the request, or one the user has seen but not approved, does not qualify. With no approved design, stop and say so rather than inventing one, and do not start a design session on the user's behalf: whether to design now, and how involved to be, is their choice.

Procedure

1. Detect where the design can be persisted. Run three checks in order and stop at the first unambiguous result:

   1. MCP tools in the session: mcp__*Atlassian*__*JiraIssue* means Jira, mcp__*github*__issue_* means GitHub Issues, mcp__*linear*__* means Linear, mcp__*gitlab*__* means GitLab Issues.
   2. The git remote (git remote get-url origin): github.com means GitHub Issues, gitlab.com means GitLab Issues. A self-hosted host may still match by substring; where it stays ambiguous, move on.
   3. CLI binaries: gh or glab on the path. A binary alone is a candidate, not a confirmation; a user can have gh installed without tracking work in GitHub Issues.

   Then resolve:

   Result	Action
   Exactly one supported system	Carry it forward. Its confirmation rides along with the step 5 gate rather than costing a separate question.
   More than one	Resolve now with AskUserQuestion. Drafting does not depend on the answer, but creation does.
   A system with no section in ./per-system-persistence.md	Tell the user the detected system is unsupported here, then take the None row.
   None	Tell the user the output will be a structured Markdown document instead of tickets, then carry on. The drafted shape changes.

2. Propose the decomposition. Read the shape off the design rather than applying a taxonomy to it:

   • Each ticket is sized to a single focused session, with acceptance criteria in three to five bullets. A component that does not fit is split before creation, not padded into a vaguer ticket.
   • Dependencies between tickets are stated where the design implies them: an integration ticket depends on the components it integrates, and cross-cutting foundations come before the work that stands on them.
   • Grouping mirrors structure the design itself names. Where the design names components or subsystems that each yield several tickets, offer that grouping; where it names none, the set stays flat, and flat is the ordinary shape rather than a degraded one. A single group wrapping every ticket adds a layer that tells the reader nothing the parent's title did not, so do not propose it.
   • Where one parent would carry an unwieldy design body, splitting into multiple parents along the design's own seams is on the table, each parent carrying in full the portion of the design its children need.

   Where two shapes are genuinely defensible, grouped or flat, one parent or several, put the choice to the user with AskUserQuestion rather than picking for them. The shape decides how the work reads for every future session, and two readers guessing separately produce trees that do not match.

3. Draft the parent body. The parent is the single source of truth for the design:

   ## Goal
   
   [One-paragraph summary of what this parent delivers]
   
   ## Design
   
   [The full approved design: architecture, key components, interfaces, data flow,
    technical decisions and trade-offs, error handling, testing strategy, and anything
    else from the design conversation that affects how the children should be built]
   
   ## Tickets
   
   - [Ticket title] - [reference once created]
   

   List the ## Tickets index in implementation order, grouped as the approved shape groups them. The index is a human convenience; the real parent-child relationships live in the ticketing system's native links. When step 1 resolved to None, read the Markdown Document section of ./per-system-persistence.md now and draft that shape instead, so the user approves at step 5 the artefact they will actually get.

   Do not replace the ## Design section with a link to an external file, a transcript, or a commit. Links rot and external context disappears; a future session opens the parent and must find everything it needs to build from.

4. Draft each child ticket with a title naming what it delivers, a description carrying the technical decisions from the design relevant to that ticket, acceptance criteria in three to five bullets, and its dependencies: a Depends on reference for each ticket that must exist first, plus its parent. A grouping ticket, where the user chose grouping, carries the group's one-sentence theme and its child references and no design content: the design lives once, in the parent, and a copy in a child is a second version waiting to drift.

5. Order the set and gate before creating anything. Build the global dependency order: foundations and cross-cutting concerns first, features next, integration after the things it integrates, polish last. A cycle in the dependency graph means no valid order exists; surface it and return to step 2 while everything is still a draft.

   Present the full set, then ask with AskUserQuestion, with three options: "Create them" (the decomposition, order and target are right), "Adjust first" (back to step 2 with the changes folded in), and "Change target" (back to step 1 to resolve the system; the decomposition survives, but the drafted bodies are redone against the new target's shape).

   This gate is the only cheap moment in the procedure. Creation writes to a system outside the repository and step 6 forbids rolling it back, so reshaping is free here and expensive or impossible afterwards. Nothing is created before "Create them".

6. Create the parent first, then the children in global dependency order, so a body saying Depends on #N is written after #N has an identifier. Use the calls for the resolved system in ./per-system-persistence.md, reading only that section.

   Failure	Response
   Parent creation fails	Nothing exists yet. Report and stop.
   A child creation fails	Stop creating immediately. Back-fill the parent with the children that did get created, report the failed child and its intended position, and leave the partial state in place.
   The back-fill itself fails	Not fatal. Native links already carry recovery and the index is a convenience. Report the stale index and continue.

   Do not silently continue past a creation failure, and do not roll back tickets that were created: rollback is a destructive operation against an external system, and whether to retry, fix and re-run, or keep the partial state is the user's call.

7. Back-fill the parent's ## Tickets index with the real references, then report: what was created, the references and links, the implementation order, any degradation the system forced (each system's degradations are documented in ./per-system-persistence.md), and any failure from step 6. This is a report, not a question; the moment to change the shape was step 5.

   Close with how to re-enter: referencing any of these tickets in a future session ("work on #42") recovers the design from the parent before implementation starts.

This skill is terminal. Do not start implementation after creating tickets: implementation from a ticket enters through recovery, which re-reads the code and confirms scope, and those checks matter even one minute after creation because the design was approved against the code as it was read, not as it is. If the user wants to begin immediately, the first ticket in the order is the one to reference.

Completion Gate

Do not report the design as persisted until all of these hold:

• An approved design existed before anything was drafted
• The user approved the set, shape and target at the step 5 gate
• Every ticket in the approved set was created, or the failure was reported per step 6
• The parent body carries the full design under ## Design, and no child does
• The report told the user how to pick the work back up

"Created" is a completion claim: it needs the actual API responses or the document on disk as evidence, not the memory of having sent the calls.

Common Mistakes