/writing-design-plans

name: writing-design-plans
description: Use after brainstorming completes - writes validated designs to docs/design-plans/ with structured format and discrete implementation phases required for creating detailed implementation plans
user-invocable: false

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):**

interface TokenService {
  generate(claims: TokenClaims): Promise<string>;
  validate(token: string): Promise<TokenClaims | null>;
}

interface TokenClaims {
  sub: string;      // service identifier
  aud: string[];    // allowed audiences
  exp: number;      // expiration timestamp
}

**Example — Implementation code (NOT OK for design plans):**

async function generate(claims: TokenClaims): Promise<string> {
  const payload = { ...claims, iat: Date.now() };
  return jwt.sign(payload, config.secret, { algorithm: 'RS256' });
}

The first defines what the boundary looks like. The second implements behavior — that belongs in implementation plans.

File Location and Naming

**File location:** `docs/design-plans/YYYY-MM-DD-<topic>.md`

The file is created by starting-a-design-plan Phase 3. This skill appends to that file.

**Expected naming convention:**

• Good: `docs/design-plans/2025-01-18-oauth2-svc-authn.md`
• Good: `docs/design-plans/2025-01-18-user-prof-redesign.md`
• Bad: `docs/design-plans/design.md`
• Bad: `docs/design-plans/new-feature.md`

Document Structure

**The design document already exists** from Phase 3 of starting-a-design-plan with this structure:

# [Feature Name] Design

## Summary
<!-- TO BE GENERATED after body is written -->

## Definition of Done
[Already written - confirmed in Phase 3]

## Acceptance Criteria
<!-- TO BE GENERATED and validated before glossary -->

## Glossary
<!-- TO BE GENERATED after body is written -->

**This skill appends the body sections:**

## Architecture
[Approach selected in brainstorming Phase 2]

[Key components and how they interact]

[Data flow and system boundaries]

## Existing Patterns
[Document codebase patterns discovered by investigator that this design follows]

[If introducing new patterns, explain why and note divergence from existing code]

[If no existing patterns found, state that explicitly]

## Implementation Phases

Break implementation into discrete phases (<=8 recommended).

**REQUIRED: Wrap each phase in HTML comment markers:**

<!-- START_PHASE_1 -->
### Phase 1: [Name]
**Goal:** What this phase achieves

**Components:** What gets built/modified (exact paths from investigator)

**Dependencies:** What must exist first

**Done when:** How to verify this phase is complete (see Phase Verification below)
<!-- END_PHASE_1 -->

<!-- START_PHASE_2 -->
### Phase 2: [Name]
[Same structure]
<!-- END_PHASE_2 -->

...continue for each phase...

**Why markers:** These enable writing-implementation-plans to parse phases individually, reducing context usage and enabling granular task tracking across compaction boundaries.

## Additional Considerations
[Error handling, edge cases, future extensibility - only if relevant]

[Don't include hypothetical "nice to have" features]

**Then this skill:** 1. Generates Acceptance Criteria (inline) and gets human validation 2. Generates Summary and Glossary to replace the placeholders

Legibility Header

The first three sections (Summary, Definition of Done, Glossary) form the **legibility header**. These sections help human reviewers quickly understand what the document is about before diving into technical details.

**Definition of Done is already written** — it was captured in Phase 3 immediately after user confirmation, preserving full fidelity.

**Summary and Glossary are generated AFTER writing the body.** This avoids summarizing something that hasn't been written yet and ensures they accurately reflect the full document.

See "After Writing: Generating Summary and Glossary" below for the extraction process.

Implementation Phases: Critical Requirements

**YOU MUST break design into discrete, sequential phases.**

**Each phase should:**

• Achieve one cohesive goal
• Build on previous phases (explici