writing-design-plans

# Writing Design Plans

## Overview

Complete the design document by appending validated design from brainstorming to the existing file (created in Phase 3 of starting-a-design-plan) and filling in the Summary and Glossary placeholders.

**Core principle:** Append body to existing document. Generate Summary and Glossary. Commit for permanence.

**Announce at start:** "I'm using the writing-design-plans skill to complete the design document."

**Context:** Design document already exists with Title, Summary placeholder, confirmed Definition of Done, and Glossary placeholder. This skill appends the body and fills in placeholders.

## Level of Detail: Design vs Implementation

**Design plans are directional and archival.** They can be checked into git and referenced months later. Other design plans may depend on contracts specified here.

**Implementation plans are tactical and just-in-time.** They verify current codebase state and generate executable code immediately before execution.

**What belongs in design plans:**

| Include | Exclude |
|---------|---------|
| Module and directory structure | Task-level breakdowns |
| Component names and responsibilities | Implementation code |
| File paths (from investigation) | Function bodies |
| Dependencies between components | Step-by-step instructions |
| "Done when" verification criteria | Test code |

**Exception: Contracts get full specification.** When a component exposes an interface that other systems depend on, specify the contract fully:

- API endpoints with request/response shapes
- Inter-service interfaces (types, method signatures)
- Database schemas that other systems read
- Message formats for queues/events

Contracts can include code blocks showing types and interfaces. This is different from implementation code — contracts define boundaries, not behavior.

**Example — Contract specification (OK):**
```typescript
interface TokenService {
  generate(claims: TokenClaims): Promise<string>;
  validate(token: stri