technical-spec

# Technical Specification & Design Documents

> Expert guidance for writing effective technical design documents, RFCs, Architecture Decision Records, and technology evaluation frameworks.

## Core Philosophy

- **Write before code** — Design documents prevent costly rework and align teams
- **Living documents** — Keep docs updated as the system evolves
- **Clarity over completeness** — Simple, direct language reduces cognitive load
- **Diagrams as code** — Version-controlled, maintainable architecture diagrams
- **Decisions over descriptions** — Document why, not just what

---

## Hard Rules (Must Follow)

> These rules are mandatory. Violating them means the skill is not working correctly.

### Alternatives Required

**Every design document must include at least 2 alternative solutions.**

```markdown
❌ FORBIDDEN:
## Solution
We will use PostgreSQL for the database.
(No alternatives considered)

✅ REQUIRED:
## Proposed Solution
PostgreSQL for primary database.

## Alternatives Considered

### Option A: PostgreSQL (Recommended)
**Pros**: ACID compliance, JSON support, mature ecosystem
**Cons**: Vertical scaling limits
**Decision**: Chosen for reliability and team expertise

### Option B: MongoDB
**Pros**: Horizontal scaling, flexible schema
**Cons**: Eventual consistency, less familiar to team
**Decision**: Rejected due to consistency requirements

### Option C: DynamoDB
**Pros**: Serverless, auto-scaling
**Cons**: Vendor lock-in, complex query patterns
**Decision**: Rejected due to query flexibility needs
```

### Diagrams Required

**System designs must include architecture diagrams. No text-only descriptions.**

```markdown
❌ FORBIDDEN:
"The user sends a request to the API, which talks to the database
and returns a response."

✅ REQUIRED:
Include at least one of:
- C4 Context/Container diagram
- Sequence diagram for key flows
- Data flow diagram

Example (Mermaid):
```mermaid
sequenceDiagram
    Client->>API: POST /orders
    API->>Auth: Validate token
    Auth-->>API: User context
    API->>DB: Create order
    DB-->>API: Order ID
    API-->>Client: 201 Created
```
```

### Success Metrics Defined

**Every design must include measurable success criteria.**

```markdown
❌ FORBIDDEN:
## Goals
- Make the system faster
- Improve reliability
- Better user experience

✅ REQUIRED:
## Success Metrics

| Metric | Current | Target | Measurement |
|--------|---------|--------|-------------|
| API Latency (P95) | 500ms | <200ms | Prometheus histogram |
| Availability | 99.5% | 99.9% | Uptime monitoring |
| Error Rate | 2% | <0.1% | Error tracking |
| Throughput | 1K req/s | 10K req/s | Load testing |
```

### Risks and Mitigations

**All designs must identify risks and their mitigations.**

```markdown
❌ FORBIDDEN:
(No risk section, assuming everything will work)

✅ REQUIRED:
## Risks & Mitigations

| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| Database migration fails | High | Medium | Backup + rollback plan, test in staging |
| Third-party API unavailable | Medium | Low | Circuit breaker, fallback cache |
| Team lacks expertise | Medium | Medium | Pair programming, external review |
| Scope creep | High | High | Fixed scope document, change control |
```

---

## When to Use This Skill

| Scenario | Document Type | Complexity |
|----------|--------------|------------|
| New feature design | Technical Design Doc | Medium-High |
| System architecture | C4 Model Diagrams | Medium |
| Major technical decision | Architecture Decision Record (ADR) | Low-Medium |
| Cross-team proposal | RFC (Request for Comments) | Medium-High |
| Technology evaluation | Tech Selection Matrix | Medium |
| API contract | OpenAPI/AsyncAPI Spec | Low-Medium |

---

## Document Types Overview

### Technical Design Document (TDD)
**Purpose**: Blueprint for implementing a feature or system
**Audience**: Engineers, technical leads
**When**: Before implementing significant features
**Sections**: Problem, solution, alternatives, risks, timeline

### RFC (Request for Comments)
**Purpose**: Proposal for discussion and feedback
**Audience**: Cross-functional teams
**When**: Need consensus on technical direction
**Sections**: Problem statement, proposal, trade-offs, open questions

### Architecture Decision Record (ADR)
**Purpose**: Document a single architectural decision
**Audience**: Current and future engineers
**When**: Any architecturally significant choice
**Sections**: Context, decision, consequences, status

### C4 Model Diagrams
**Purpose**: Visualize system architecture at multiple zoom levels
**Audience**: Technical and non-technical stakeholders
**When**: Communicating system structure
**Levels**: Context, Container, Component, Code

---

## Essential Document Sections

### 1. Front Matter

```markdown
# Title: User Authentication System

**Author**: Jane Doe
**Status**: Proposed | In Review | Approved | Implemented
**Created**: 2025-12-18
**Last Updated**: 2025-12-18
**Reviewers**: @tech-lead, @security-team
```

### 2. Problem Statement (The "Why")

```markdown
## Problem

**Current State**: Users authenticate via legacy session cookies, no MFA support.
**Impact**: 23% of security incidents related to compromised credentials.
**Constraint**: Must support 10K concurrent users, <200ms login latency.
**Goal**: Implement secure, scalable authentication with MFA and OAuth support.
```

### 3. Proposed Solution (The "What")

```markdown
## Solution

Implement JWT-based authentication with:
- Access tokens (15min TTL) + Refresh tokens (7 day TTL)
- TOTP-based MFA (Google Authenticator compatible)
- OAuth 2.0 providers (Google, GitHub)
- Redis for token blacklist and session management

### High-Level Design

[Include C4 Container diagram here]

### Data Flow

1. User submits credentials → Auth Service validates
2. Auth Service generates JWT pair, stores refresh token in Redis
3. Client includes access token in Authorization header
4. API Gateway validates token, extracts u