writing-design-plans

What this skill does

# 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: 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):**
```typescript
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:

```markdown
# [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:**

```markdown
## 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:**

| Phase Type | Done When | Examples |
|------------|-----------|----------|
| Infrastructure/scaffolding | Operational success | Project installs, builds, runs, deploys |
| Functionality/behavior | Tests pass that verify the ACs this phase covers | Unit tests, integration tests, E2E tests |

**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/ty