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.

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

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.

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

### 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 user context
5. On expiry, client exchanges refresh token for new access token

4. Alternatives Considered

## Alternatives

### Option A: Session-based authentication
**Pros**: Simpler implementation, server-side revocation
**Cons**: Doesn't scale horizontally, higher latency
**Decision**: Rejected - doesn't meet scalability requirements

### Option B: Auth0 (3rd party)
**Pros**: Battle-tested, feature-complete
**Cons**: $500/month cost, vendor lock-in
**Decision**: Deferred - revisit if team velocity insufficient

5. Risk Assessment

## Risks & Mitigations

| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| JWT secret leak | Critical | Low | Rotate secrets quarterly, use HSM |
| Token theft (XSS) | High | Medium | HttpOnly cookies, CSP headers |
| Redis downtime | High | Low | Fallback to stateless validation |
| Clock skew issues | Medium | Medium | Use `nbf` claim, allow 5min tolerance |

6. Implementation Plan

## Work Breakdown

### Phase 1: Core Authentication (Week 1-2)
- [ ] JWT generation/validation service
- [ ] Password hashing (bcrypt)
- [ ] User repository interface
- [ ] Unit tests + integration tests

### Phase 2: MFA (Week 3)
- [ ] TOTP secret generation
- [ ] QR code generation
- [ ] Verification endpoint
- [ ] Backup codes

### Phase 3: OAuth (Week 4)
- [ ] Google OAuth integration
- [ ] GitHub OAuth integration
- [ ] Account linking flow

### Success Metrics
- 100% test coverage for auth logic
- <100ms token validation latency
- Zero security vulnerabilities in audit

7. Open Questions

## Open Questions

1. **Token storage**: Should refresh tokens be in httpOnly cookie or localStorage?
   - **Recommendation**: Cookie (XSS protection), need CSRF mitigation

2. **MFA enforcement**: Opt-in or mandatory for all users?
   - **Requires**: Product team decision

3. **Session limits**: Should we limit concurrent sessions per user?