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:

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 (explicit dependencies)
• End with a working build and clear "done" criteria
• Use exact file paths and component names from codebase investigation

Phase Verification

Verification depends on what the phase delivers:

The rule: If a phase implements functionality, it must include tests that verify the specific acceptance criteria it claims to cover. Tests are a deliverable of the phase, not a separate "testing phase" later.

Tying tests to ACs: A functionality phase lists which ACs it covers (e.g., oauth2-svc-authn.AC1.1, oauth2-svc-authn.AC1.3). The phase is not "done" until tests exist that verify each of those specific cases. This creates traceability: AC → phase → test.

Don't over-engineer infrastructure verification. You don't need unit tests for package.json. "npm install succeeds" is sufficient verification for a dependency setup phase. Infrastructure phases typically don't list ACs—their verification is operational.

Do require tests for functionality. Any code that does something needs tests that prove it does that thing. These tests must map to specific ACs, not just "test the code." If a phase covers oauth2-svc-authn.AC1.3 ("Invalid password returns 401"), a test must verify exactly that.

Tests can evolve. A test written in Phase 2 may be modified in Phase 4 as requirements expand. This is expected. The constraint is that Phase 2 ends with passing tests for the ACs Phase 2 claims to cover.

Structure phases as subcomponents. A phase may contain multiple logical subcomponents. List them at the component level — the implementation plan will break these into tasks.

Good structure (component-level):

<!-- START_PHASE_2 -->
### Phase 2: Core Services
**Goal:** Token generation and session management

**Components:**
- TokenService in `src/services/auth/` — generates and validates JWT tokens
- SessionManager in `src/services/auth/` — creates, validates, and invalidates sessions
- Types in `src/typ