/technical-spec

name: technical-spec
description: Technical specification and design document expert. Use when writing design docs, RFCs, ADRs, or evaluating technology choices. Covers C4 model, system design, and architecture documentation.

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.**

❌ 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.**

❌ 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.**

❌ 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

# 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")

## 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")

## 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]