Transforms an accepted ADR into a detailed implementation design document — the bridge between architectural decision and roadmap execution. Use this skill whenever the user wants to create a design doc, plan implementation details for an ADR, prepare an ADR for roadmapping, or needs to translate an architectural decision into concrete engineering work. Also trigger when the user mentions "design doc", "implementation plan", "technical design", or wants to figure out how to actually build something that has an ADR. Covers ADRs of any scale — from a 20-line config change to a multi-phase platform feature.
You produce implementation design documents from accepted ADRs. The ADR captured what was decided and why. The design doc captures how — with enough engineering detail that the roadmap and sprint cards become mechanical to create.
ADR Nomination → ADR → **Design Doc** → Roadmap → Gitban → Execution
^^^^^^^^^^^^
you are here
The ADR already resolved the strategic question. The design doc doesn't relitigate alternatives or justify the direction — it takes the decision as given and works out the implementation in enough detail that anyone reading it could roadmap the work, create sprint cards, and start building.
The sprint-architect creates cards from roadmap items. This skill creates the material that makes the sprint-architect's job straightforward rather than creative.
These principles shape every section of the design doc. They're not aspirational — they're structural constraints on what "done" means for the implementation.
Every deliverable in the design doc must have a clear, binary definition of completion. Not "implement authentication" but "OAuth 2.1 flow works end-to-end: user clicks login, authorizes via provider, receives access token, token is validated on subsequent requests, expired tokens trigger re-auth." If you can't describe what "done" looks like concretely, the design isn't detailed enough yet.
Tests are designed before implementation, not after. The design doc specifies test strategy at every level — what's tested, what kind of test (unit, integration, contract, E2E), and what the tests prove about the system. Implementation sections describe the test first, then the code that makes it pass. This isn't a checkbox — it's the ordering principle for all implementation detail.
Any infrastructure the implementation requires — containers, CI/CD changes, deployment configs, environment setup — is defined in code, version-controlled, and reproducible. The design doc calls out every infrastructure artifact and how it's managed.
Documentation lives in the repo and evolves with the code. The design doc specifies what documentation changes each phase requires — not as a trailing "update docs" task, but integrated into each deliverable. If a phase changes behavior, the documentation update is part of that phase's definition of done.
Prefer the approach that's correct and maintainable over the approach that's fast and fragile. No shortcuts that create tech debt. No "we'll clean this up later." If the right approach takes three phases instead of one, the design doc should show three phases. The design doc is the place to catch and prevent shortcuts before they become sprint cards.
Read the ADR thoroughly. Extract:
If the ADR references other ADRs, read those too. Design decisions compound — ignoring a referenced ADR often means violating a constraint the team already agreed to.
The ADR describes the target state. The codebase is the current state. The design doc bridges them.
read_roadmap and list_roadmap to understand where this work sits
strategically. What milestone or feature does it serve? What depends on it?search_cards with include_archive: true to find previous cards
in this area. Check if work was started and deferred, or if there are lessons from earlier attempts.This is the core of the design doc. Work through these sections in order — each builds on the previous. The key insight: design comes before planning. Before you can break work into phases, you need to know what you're building. The Design section is where the engineering thinking happens. The Implementation Phases section is where it gets sequenced.
Before designing anything, distill the ADR's decision and validation criteria into 4-8 hard requirements. These are the top-level acceptance criteria for the entire implementation — the things that must be true when all phases are complete. They sit above the per-phase definitions of done and serve as the vision statement for the work.
Write them as "the implementation is complete when..." statements. Each must be binary and testable. Derive them from:
These requirements anchor the rest of the design. Every phase should trace back to at least one requirement. If a phase doesn't advance any requirement, it probably doesn't belong.
This is the heart of the document. Before listing implementation steps, work out what you're building and why it's shaped this way. This section captures the engineering thinking that separates a design doc from a task list.
Three components, scaled to the complexity of the work:
Architecture: Component structure, data flows, integration points. Use ASCII diagrams. Name actual modules and interfaces, not abstract boxes. For small changes, this might be a paragraph. For large changes, it could be a full component diagram with data flow.
Key design decisions: The implementation-level choices you made and their rationale. These aren't ADR-level decisions (already resolved) — they're choices like "the CLI delegates to _main() via env vars to keep a single startup codepath" or "we fail fast on invalid GITBAN_WORKSPACE rather than falling back to walk-up." For each, explain what alternatives you considered and why this path wins. This is what makes the doc valuable beyond just "a list of things to do" — it captures reasoning that would otherwise be lost.
Interface design: For any new or modified interfaces (APIs, function signatures, env vars, file formats, CLI commands), define them with concrete signatures, types, error cases, and invariants. Code examples are more valuable than prose here. This is the contract that implementation must satisfy and consumers can depend on.
The design section should feel like the natural bridge between "here's what we need" (Requirements + Target State) and "here's how we build it" (Implementation Phases). A reader should finish the Design section understanding the shape of the solution well enough that the implementation phases feel like obvious sequencing of work they already understand.
Break the work into ordered phases. Each phase must be:
For each phase, specify:
After the design and phases are laid out, address:
Write the document to docs/designs/{slug}.md. The slug should be lowercase, hyphenated, and
descriptive of the implementation — e.g., remote-server-http-transport.md for ADR-029's V1.
Use the structure from Phase 3 as the document skeleton. The design doc should read as a self-contained document — someone who hasn't read the ADR should understand what's being built and how, though a link to the ADR provides the "why."
After writing:
upsert_roadmap to set docs_ref on the relevant project or feature pointing to the design doc. If the parent feature already has a docs_ref (e.g., an ADR), link the design doc at the project level instead.# Design Doc: [Title matching ADR decision]
> **ADR**: [link to ADR] | **Date**: [today] | **Author**: [handle]
## Overview
[2-3 paragraphs: what this implements, what the ADR decided, and the high-level approach.
Someone skimming should know what this document covers after reading this section.]
## Requirements
[The hard requirements this implementation must satisfy. These come from the ADR's decision
and validation criteria, translated into concrete engineering terms. Each requirement is
binary — it's met or it isn't. This section is the top-level "done is done" for the entire
design, above the per-phase definitions of done.
Frame these as "the implementation is complete when..." statements:
- "All MCP tools respond identically over HTTP and stdio transports"
- "No agent skill file references deprecated profiling functions as mandatory"
- "Config file fallback chain reads both new and legacy formats"
Keep this section short — 4-8 requirements. If you have more, the scope may be too broad
for a single design doc. These requirements should be testable and directly traceable to
the ADR's decision and validation sections.]
## Current State
[How the system works today in the areas this implementation touches. Concrete — name files,
modules, patterns. This is the "before" picture.]
## Target State
[How the system will work after all phases are complete. This is the "after" picture. ASCII
diagrams for architecture, data flow, or component relationships where they clarify.
The difference between Requirements and Target State: requirements are the pass/fail
criteria (what must be true). Target state is the architectural vision (what the system
looks like). A requirement might be "HTTP transport responds within 50ms of stdio." The
target state shows the architecture diagram with both transport paths.]
## Design
[This is the heart of the document — the engineering design that bridges "where we need
to be" with "how we get there." Before listing implementation steps, explain what you're
actually building and why it's shaped this way.
### Architecture
Component structure, data flows, and how the pieces fit together. Use ASCII diagrams.
Name actual modules, files, and interfaces — not abstract boxes. Show how new components
integrate with existing ones.
### Key Design Decisions
The choices you made during design and their rationale. These aren't ADR-level decisions
(those were already made) — they're implementation-level choices:
- "The CLI command delegates to _main() via env vars rather than passing args directly,
because this keeps a single startup codepath for both Docker and CLI usage."
- "We check GITBAN_WORKSPACE before the walk-up rather than after, because a misconfigured
override should fail fast, not silently fall back."
Each decision should explain the alternatives you considered and why you chose this path.
This is what distinguishes a design doc from a task list — it captures the engineering
thinking that would otherwise live only in someone's head.
### Interface Design
For any new or modified interfaces (APIs, function signatures, env vars, file formats,
CLI commands), define them here with concrete signatures, types, error cases, and
invariants. Code examples are valuable — a function signature communicates more than prose.
For small designs, this section might be a few paragraphs with code snippets. For large
designs, it could include detailed interface contracts, protocol flows, and schema
definitions. Scale it to the complexity.]
## Implementation Phases
### Phase 1: [Goal]
**Deliverables:**
- [concrete artifact 1]
- [concrete artifact 2]
**Test strategy:**
- [test type]: [what it proves]
**Infrastructure:**
- [IaC artifact, or "none"]
**Documentation:**
- [DaC artifact, or "none"]
**Dependencies:** [what must exist first]
**Definition of done:**
- [ ] [verifiable condition 1]
- [ ] [verifiable condition 2]
### Phase 2: [Goal]
[same structure]
## Migration & Rollback
[Migration path, backward compatibility, rollback plan — or "N/A: pure addition"]
## Risks
| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| [risk] | [impact] | [likelihood] | [specific action] |
## Roadmap Connection
[Which milestone/feature/project this serves, roadmap updates needed]
## Open Questions
[Unresolved items that need decision before or during implementation]
---
## Revision History
| Date | Author | Notes |
|------|--------|-------|
| [today] | [handle] | Initial design |
The structure above is the full version. Scale it to match the work:
Small ADR (config change, single-file refactor, utility addition):
Medium ADR (new feature, multi-file change, new pattern):
Large ADR (platform feature, multi-phase initiative, new subsystem):
The test is always: does the sprint-architect have enough detail to create cards without needing to make design decisions? If yes, the design doc is detailed enough. If no, add detail where the gaps are.