to-design — PRD to Design Document

Turn a PRD (or a rough idea) into a design document written in the style of Go's official design proposals: plain language, concrete examples, and—above all—an honest account of why this approach and not the alternatives.

This is not the same as

prd-to-spec

. A SPEC is an implementation contract (tables, endpoints, schemas) for an engineer to build against. A design document is a decision artifact: it argues for an approach, surfaces the tradeoffs, and lets a team agree on the same facts before anyone writes code. When the question is "how should we build this and why", produce a design doc; when the question is "give me the exact contract to implement", produce a SPEC.

The design philosophy is derived from the analysis of 5 official Go proposals (generics / error wrapping / loopvar / slog / try). Core belief: The value of a document does not depend on whether the proposal is accepted, but on whether it enables discussions to be grounded in the same set of facts and tradeoffs.

When to Use

A PRD exists and you need to decide how to build it before committing to implementation
The approach has real tradeoffs and you want them documented and debated
The change is risky, breaking, or hard to reverse (a design doc forces the compatibility conversation early)
Multiple people need to agree on a direction before work fans out
You want a durable record of "why we chose X and rejected Y" — even if the proposal is later rejected

If the team just needs the concrete contract to code against, use

/prd-to-spec

instead (or run

to-design

first, then

prd-to-spec

The Job

Locate input — find or receive the PRD (or idea)
Analyze context (optional) — scan the codebase for existing patterns, constraints, and prior art
Surface the decisions — identify the real design forks and ask clarifying questions (max 3-5)
Generate the design doc — following the structure and writing style below
Review — present for feedback, especially on the Rationale and Compatibility sections
Save — write to the agreed location

Step 1: Locate Input

Provide the PRD (or idea) to design from:

A. File path (e.g., tasks/prd-priority-system.md)
B. GitHub Issue URL
C. Paste content directly
D. Just describe the idea — I'll design from the conversation

A design doc can start from a half-formed idea, not only a polished PRD. If the input is thin, lean harder on Step 3.

Step 2: Analyze Context (Optional)

Skip for greenfield. Otherwise scan to ground the design in reality:

Existing patterns the design should match (naming, error handling, module boundaries)
Prior art — has something similar been tried or rejected here before?
Constraints — compatibility promises, public APIs, data the design can't break
Real pain — find the actual buggy/awkward code the design fixes, so Background can quote it

The most persuasive Background sections quote real code from the user's own repo, not hypotheticals.

Step 3: Surface the Decisions

A design doc lives or dies on its Rationale. Before writing, find the real forks in the road — the points where a competent engineer could reasonably go two ways — and resolve them.

Ask only about genuine forks:

Design decisions to settle before I write the doc:

1. Where does this logic live?
   A. Extend the existing X
   B. New standalone component Y
   C. Let me recommend based on the codebase

2. Is this a breaking change for existing callers?
   A. Yes — needs a migration path
   B. No — purely additive
   C. Unsure — I'll analyze and flag it

3. What's the one promise this design must keep? (e.g. backward compatibility,
   latency budget, no new dependencies)

For every fork, also note the option you are NOT choosing — that becomes the Rationale.

Step 4: Design Document Structure

This is the standard skeleton distilled from the 5 Go proposals. Keep section names; drop sections that genuinely don't apply (and say why if the omission is notable).

markdown

Title: <A one-sentence statement of "what to do" — the title is a conclusion, not a noun phrase>
Author(s): <Author(s)>
Last updated: <YYYY-MM-DD>
Discussion at <issue / PR / document link>   # Keep the document connected, always attach an entry for discussions
Status: Draft | Under review | Accepted | Rejected

## Abstract / Abstract

A single paragraph summarizing the entire document: what to do, how to do it roughly, and **the most critical promise** (e.g., "backward compatibility", "no new dependencies").
Readers should grasp the full picture after this paragraph. Embed implicit core constraints here.

## Background / Background & Motivation

Use **specific, tangible examples** to explain "where the pain lies" instead of abstractly stating "the current state is bad".
- Paste a snippet of real buggy code / awkward usage if possible. First make readers "feel the pain".
- Quantify pain points (frequency of occurrence, number of pitfalls, losses) instead of using vague adjectives.
- Qualify the problem in one sentence.

## Design / Proposal / Design

The main body of the document. Follow three rules:
- **Progressive teaching from simple to complex**: Start with the smallest example, leave complex scenarios until readers have an intuition.
- **Triad of declaration + example + boundary**: For each API/interface, first provide the declaration, then a usage snippet, then clarify the applicable boundaries.
- **Before vs after transformation comparison**: Display side-by-side to show benefits whenever possible.
Never use a paragraph of text when a runnable code snippet can explain it clearly.

## Rationale / Rationale & Tradeoffs

> Rationale = The argument for "why this solution, not others". This is the key section that distinguishes good documents from mediocre ones.

- Explain the motivation behind key decisions.
- **Proactively list rejected alternatives + reasons for rejection** ("We did not choose X because Y"). This is more credible than unilaterally justifying your chosen solution, and prevents repeated discussions by future teams.
- Address foreseeable objections.

## Compatibility / Compatibility

For any breaking changes, you must respond directly.
- Is this a breaking change? **State it clearly upfront**.
- What are the costs (performance, behavior changes, migration costs)? **List them honestly**, no hiding.
- Gradual migration paths (opt-in by module/file, canary releases, feature flags).
- It's better to have precedents ("A similar change was made in a certain system with unremarkable results").

## Implementation / Transition / Implementation & Transition

- How to implement it, in what steps, and supporting tools.
- **Use data and tools to support "feasibility"**: Measured failure rates, canary release results, automated migration tools are more convincing than any "we believe risks are controllable".
- Transition plans to maintain compatibility with old versions (e.g., independently released compatibility libraries).

## Appendix / Appendix (Optional)

Move details that would interrupt the main narrative to the end: complete APIs, end-to-end examples, FAQs.
FAQs specifically address high-frequency questions ("Why this name?", "Why not use the approach of a certain language?", "How is this different from X?").

Writing Style (Adhere strictly to Go documentation style)

Structure is the skeleton; style is the muscle. Enforce these — they're what make the doc readable.

Voice / Subject

Use "We" for decisions — Frame the design as a choice that a group takes responsibility for, not an objective truth. ("We propose…", "We decided to remove…")
Use the code itself as the subject for actions — "this code has a bug" / "this code will…" to focus attention on the program.
Use "you" when explaining to readers — As if explaining face-to-face.
Avoid subject-less passive voice — Do not use evasive phrases like "It is suggested that…" or "According to suggestions, we should…".

Sentences / Sentences

Use short sentences for judgments, long sentences for arguments. First make a decision with an extremely short sentence ("This code has a bug."), then elaborate on the mechanism with information-dense long sentences.
Alternate between short and long sentences to create rhythm. Avoid using meandering long sentences throughout.

Paragraphs / Paragraphs

Each paragraph focuses on one thing, with the point at the beginning (conclusion first).
Write subheadings as complete argumentative sentences, not noun phrases.
- Write
```
Legacy code is unaffected, compilation results are identical to before
```
  instead of
```
Compatibility
```
  .
- Readers can follow the entire argument chain just by reading the headings.

Tone / Tone

Restrained honesty, even self-deprecation. Acknowledging costs and admitting you've made mistakes is more persuasive than adjectives.
Use emphasis sparingly. Bold/italicize only once at the most critical point in the entire document to make it stand out.

Step 5: Review & Iteration

Present the doc and steer feedback to the sections that matter most:

The design document has been generated. Please focus on these sections:

- Rationale: Are the rejected alternatives and their reasons valid? Are there any missing alternatives?
- Compatibility: Are the breaking changes and costs stated honestly? Is the migration path feasible?
- Background: Are pain points explained with specific examples instead of adjectives?
- Writing style: Are the titles conclusions rather than noun phrases? Is there any subject-less passive voice?

Reply "OK" to save, or provide revision suggestions.

Step 6: Save

Where to save the design document?

A. tasks/design-[feature-name].md (Next to the PRD, recommended)
B. docs/design/[feature-name].md
C. Custom path: [Specify]

Mapping: PRD → Design Doc

PRD Section	Design Doc Section	Transformation Method
Problem / Background	Background	Find real pain point code/scenarios and quantify them
Goals / Objectives	Abstract + Background	Refine into the "most critical promise" and embed it in the abstract
User Stories / Requirements	Design	Convert into progressive design examples
Technical Considerations	Design + Rationale	Constraints → Design decisions + tradeoff arguments
Non-Goals	Rationale	Write as "We did not do X because Y"
Risks / Risks	Compatibility + Implementation	Risks → Compatibility costs + migration/canary release plans
Implicit Alternatives	Rationale	Explicitly list and explain why they were rejected

Quality Criteria

A good design doc should pass these checks:

The title is a one-sentence conclusion of "what to do", not a noun phrase, and includes a discussion link
The most critical promise/constraint is embedded in the abstract
Background uses specific examples or real code to explain pain points, not adjectives
Design follows the "declaration + example + boundary" rule and uses progressive teaching
Rationale proactively lists at least one rejected alternative and its reason (the most critical check item)
For any breaking changes, Compatibility clearly acknowledges them and lists the costs
Implementation uses data/tools to support "feasibility" instead of empty claims like "risks are controllable"
Writing style: Uses "We" for decisions, code as the subject for actions, no subject-less passive voice; alternates between short and long sentences; subheadings are argumentative sentences
No "TBD / TODO" items — either resolve them or move them to Open Questions

Edge Cases & Fallback

Scenario	Handling
Vague or incomplete PRD	Ask more questions in Step 3, and record missing items in Open Questions / Assumptions
No real pain point code to reference	Replace with the smallest credible sample code and note that it is constructed
No alternatives to write	Force yourself to think "What is the most naive approach and why is it insufficient?" — there is always a rejected baseline
Non-breaking change	Compatibility section can simply state "Purely additive, no breaking changes" without unnecessary elaboration
Proposal is ultimately rejected	Still write the document well — recording "why this path didn't work" is a high-value product in itself; mark Status as Rejected
Feature is too large	Split into multiple design docs (by boundaries) and link them to each other
User only needs implementation contract	Prompt to use `/prd-to-spec` instead, or run `to-design` first then `prd-to-spec`

Anti-Patterns to Avoid

Don't only justify your chosen solution. Without listing rejected alternatives, the document loses half its value.
Don't use adjectives to explain pain points. "The current state is bad" is not persuasive; a snippet of real buggy code is.
Don't hide costs. Performance degradation, behavior changes, migration costs — state them clearly and provide a migration path.
Don't write titles as nouns. "Compatibility" → "Legacy code is unaffected, compilation results are identical to before".
Don't use subject-less passive voice. Decisions need accountability; use "We" as the subject.
Don't write it as a SPEC. A design document focuses on "why this choice was made" and "tradeoffs", not a field-level implementation contract.
Don't cut corners just because the proposal might be rejected. The quality of the document is independent of whether the proposal is accepted.

Relationship to Other Skills

/prd  →  /to-design  →  /prd-to-spec  →  /goal  →  /review-it  →  /ship-it
 │            │               │              │
 │ Requirements(what) │ Decisions & Tradeoffs │ Implementation Contract(how) │ Coding
 │            │ (why/which)   │

/prd Generates PRD (input for this skill)
/to-design Generates design document: argues for the solution, exposes tradeoffs, aligns team understanding (this skill)
/prd-to-spec Generates implementation-level SPEC: field, interface, schema contracts
/code-to-spec Reverses existing code into SPEC (complementary: forward vs reverse)

The ultimate goal of writing a design document is not "to convince others to agree with you", but "to enable everyone to make decisions based on the same set of facts and tradeoffs."

to-design

NPX Install

Tags

SKILL.md Content (Chinese)