tech-spec

Technical Specification Document

A tech spec is the bridge between "what we want to build" and "how we'll build it." It forces clarity before code is written, surfaces risks early, and creates alignment across the team.

Quality Directive: Before producing or reviewing a tech spec, read the quality-standard skill. Apply the self-verification protocol (completeness, precision, consistency, executability), edge case prompting (data, concurrency, failure modes, security, operational), and anti-pattern awareness (solutions without problems, hand-wavy security, optimistic migrations, missing error paths, hidden scope creep). Use the Spec Self-Review Checklist and Anti-Patterns sections at the end of this document before submitting specs for review.

Spec Structure

# [Feature/System Name] — Technical Specification

**Author**: [Name]
**Reviewers**: [Names]
**Status**: Draft | In Review | Approved | Implemented
**Created**: [Date]
**Last Updated**: [Date]

## 1. Overview
[2-3 sentences explaining what this is and why we're building it.
Should be understandable by any engineer on the team.]

## 2. Goals & Non-Goals

### Goals
- [What this project WILL accomplish — be specific and measurable]

### Non-Goals
- [What this project explicitly WILL NOT do — prevents scope creep]

## 3. Background
[Context needed to understand the design. Current system state,
user pain points, business requirements, relevant metrics.]

## 4. Detailed Design

### 4.1 Architecture Overview
[High-level diagram or description of how components interact.
Include a Mermaid diagram when helpful.]

### 4.2 Data Model
[Database schema changes, new tables/collections, key relationships.
Show the actual schema, not just prose descriptions.]

### 4.3 API Design
[New or modified endpoints. Include request/response examples.
For internal APIs, define the interface contract.]

### 4.4 Key Algorithms / Business Logic
[Any non-trivial logic that needs careful thought.
Pseudocode or flowcharts for complex flows.]

### 4.4 Error Handling

**MANDATORY: Error Handling Matrix**

| Error Type | Detection | Response | Recovery |
|---|---|---|---|
| [network timeout] | [how detected: timeout exception after X ms] | [immediate action: retry with exponential backoff] | [user experience: show timeout message after 3 retries] |
| [invalid input] | [how detected: validation schema fails] | [immediate action: log validation error, reject request] | [recovery: return specific error code to caller] |
| [database connection fail] | [how detected: connection pool exhaustion] | [immediate action: circuit breaker opens] | [recovery: fallback to read-only cache, escalate alert] |
| [auth failure] | [how detected: token validation fails] | [immediate action: reject request, log attempt] | [recovery: require fresh login, audit trail] |
| [rate limit exceeded] | [how detected: request count exceeds threshold] | [immediate action: queue or reject] | [recovery: backoff retry with jitter] |
| [external API slow] | [how detected: latency > p99 threshold] | [immediate action: timeout at X ms] | [recovery: degrade gracefully, use cached data if available] |

### 4.5 Data Flow Diagrams

**MANDATORY**: Provide at least one diagram showing:
- Input sources (user, API, events, scheduled jobs)
- Processing steps (validation, transformation, business logic, external calls)
- Output destinations (database, cache, queue, external API, user response)
- Where errors can occur and how they propagate
- Concurrency points and potential race conditions

Use Mermaid flowchart or sequence diagram format. Include in the diagram:
- The exact order of operations
- Which operations can fail independently
- What state is persisted at each step
- How partial failures are handled

## 5. Security Considerations

**MANDATORY: Security Checklist** — All items must be explicitly addressed (✓ implemented, or ○ N/A with justification):

- [ ] **Authentication**: Which services/endpoints require auth? What method (OAuth, JWT, API key, mutual TLS)? Token expiration and refresh? Service-to-service auth?
- [ ] **Authorization**: How are permissions checked? Role-based, attribute-based, or resource-based? Who decides access? IDOR prevention (can user A access user B's resource)?
- [ ] **Encryption**: Data at rest (database, cache, backups)? Data in transit (TLS version, certificate validation)? Key management (rotation, storage, access)?
- [ ] **Input Validation**: All untrusted inputs validated at trust boundary? Schema validation, type checking, length limits, format validation (regex)? SQL injection, XSS, command injection, template injection prevention?
- [ ] **PII Handling**: What is classified as PII (emails, phone, SSN, location, etc.)? Where is it stored? Who can access it? Retention policy? Anonymization/pseudonymization strategy?
- [ ] **Audit Logging**: Which actions are audited? What is logged (who, what, when, where, outcome)? Where are audit logs stored and how long retained? Who has access?
- [ ] **OWASP Top 10 Check**: A1 Broken Access Control, A2 Cryptographic Failures, A3 Injection, A4 Insecure Design, A5 Security Misconfiguration, A6 Vulnerable & Outdated Components, A7 Authentication Failures, A8 Data Integrity Failures, A9 Logging & Monitoring Failures, A10 SSRF. Which apply? How addressed?
- [ ] **Rate Limiting & Abuse Prevention**: Per-user, per-IP, or per-resource limits? Enforcement mechanism? Bypass or whitelisting logic?
- [ ] **Secrets Management**: How are credentials, API keys, database passwords stored? Never in code or environment variables without encryption. Use secret vault. Rotation policy?

## 6. Performance & Scalability

**MANDATORY: Load Estimation & Performance Targets** — All of the following must be populated with specific numbers:

### 6.1 Load & Capacity Planning

| Metric | Target | Rationale |
|---|---|---|
| **Expected RPS** | [e.g., 1,000 RPS peak] | [source: user growth forecast, production historical data] |
| **Concurrent Users** | [e.g., 10,000 concurrent] | [source: peak hour calculation] |
| **Data Volume** | [e.g., 1M records/day ingestion] | [source: growth rate, retention policy] |
| **Storage Required (Year 1)** | [e.g., 500 GB] | [source: average record size × volume × retention months] |

### 6.2 Latency & Throughput Targets

| Metric | Target | SLA |
|---|---|---|
| **p50 latency** | [e.g., 50 ms] | [e.g., 95% of requests] |
| **p99 latency** | [e.g., 200 ms] | [e.g., 99% of requests] |
| **Throughput (queries/sec)** | [e.g., 5,000 QPS] | [e.g., sustained] |
| **Error rate** | [e.g., < 0.1%] | [e.g., 99.9% availability] |

### 6.3 Database Query Performance

**MANDATORY**: For each critical query/operation, specify:
- Query pattern (SELECT/INSERT/UPDATE)
- Expected execution time ([e.g., < 10 ms](e.g., < 10 ms))
- Index strategy (which columns indexed)
- Estimated row scan count (prevent N+1, unbounded queries)
- Example query with EXPLAIN PLAN

**Minimum Requirements**:
- [ ] Max result set size per query (include LIMIT)
- [ ] Estimated query count per user request (prevent 10+ queries per endpoint)
- [ ] Caching strategy for expensive queries (TTL, invalidation)

### 6.4 Payload & Network Analysis

| Component | Size | Frequency | Impact |
|---|---|---|---|
| [e.g., user profile fetch] | [e.g., 5 KB] | [e.g., per request] | [e.g., 5 MB/sec at peak] |
| [e.g., image upload] | [e.g., max 10 MB] | [e.g., occasional] | [e.g., handled async] |

### 6.5 Caching Strategy

- [ ] What data is cached (queries, API responses, session data)?
- [ ] Cache TTL for each data type (seconds/minutes/hours)?
- [ ] Cache invalidation strategy (TTL expiry, event-driven, batch cleanup)?
- [ ] Cache key naming convention?
- [ ] Fallback if cache is unavailable?
- [ ] Estimated cache hit rate (%), memory footprint (MB)?

### 6.6 Bottleneck Analysis & Mitigation

- [ ] CPU-bound operations (optimization, parallelization)?
- [ ] I/O-bound operations (connection pooling, batching, async)?
- [ ] Database bottlenecks (indexing, partitioning, read replicas)?
- [ ] Network bottlenecks (compression, pagination, lazy loading)?
- [ ] Third-party API constraints (rate limits, SLA)?

## 7. Observability
[Key metrics to track, alerting thresholds, logging strategy,
dashboards needed, SLIs/SLOs if applicable.]

## 8. Migration / Rollout Plan
[How to deploy safely. Feature flags? Gradual rollout?
Database migration strategy? Backward compatibility?
Rollback plan if things go wrong?]

## 9. Testing Strategy
[Unit test approach, integration test plan, E2E scenarios,
load testing requirements, manual QA checklist.]

## 10. Dependencies & Risks

### 10.1 External Dependencies

| Service | Version | SLA | Fallback Strategy |
|---|---|---|---|
| [e.g., Stripe API] | [e.g., v1.2] | [e.g., 99.9%] | [e.g., queue for retry, manual review] |
| [e.g., Redis] | [e.g., 7.0] | [e.g., 99.95%] | [e.g., fallback to in-memory cache] |

### 10.2 Team Dependencies

| Team/Person | Dependency | Timeline | Risk |
|---|---|---|---|
| [e.g., Backend team] | [e.g., new API endpoint] | [e.g., 2 weeks] | [e.g., blocks our QA schedule] |
| [e.g., Database team] | [e.g., schema migration approval] | [e.g., 1 week] | [e.g., downtime window limited] |

### 10.3 Risk Matrix

**MANDATORY**: For each identified risk, populate all columns:

| Risk | Probability (H/M/L) | Impact (H/M/L) | Severity | Mitigation Strategy | Owner | Deadline |
|---|---|---|---|---|---|---|
| [e.g., Third-party API latency increases during peak traffic] | [e.g., M] | [e.g., H] | [e.g., HIGH] | [e.g., Implement circuit breaker, load testing with degraded API performance] | [e.g., @john] | [e.g., 2 weeks before launch] |
| [e.g., Database replication lag causes stale reads] | [e.g., L] | [e.g., H] | [e.g., MEDIUM] | [e.g., Read from primary for critical operations, eventual consistency acceptable for analytics] | [e.g., @jane] | [e.g., 1 week] |
| [e.g., New infrastructure requires capacity planning] | [e.g., H] | [e.g., M] | [e.g., MEDIUM] | [e.g., Provision 2x expected load, auto-scaling policy] | [e.g., @infra-team] | [e.g., 3 weeks] |
| [e.g., Security review uncovers critical issues] | [e.g., M] | [e.g., H] | [e.g., HIGH] | [e.g., Reserve time for fixes, early security review (2 weeks pre-launch)] | [e.g., @security] | [e.g., 4 weeks before launch] |

**Risk Scoring**:
- **CRITICAL**: H × H (blocks launch, immediate action required)
- **HIGH**: H × M or M × H (must be resolved before production)
- **MEDIUM**: M × M, H × L, or L × H (resolve before launch, monitor post-launch)
- **LOW**: M × L or L × M or L × L (document, monitor)

## 11. Timeline & Milestones
[Rough breakdown of work phases. Not a project plan —
just enough to show the scope is reasonable.]

## 12. Open Questions
[Things that still need answers. Tag the person who can answer.]

## Appendix
[Reference materials, benchmarks, research, related specs.]