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](../quality-standard/SKILL.md) 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.,  "We will implement a microservice to handle payment processing, using event sourcing and CQRS pattern."

**Problem**: Why? What user problem does this solve? Why not keep payments in the monolith?

**Fix**: Start with background. "Currently, payment processing blocks the checkout flow, causing 10% of users to abandon. P99 latency is 5 seconds. Goal: P99 latency  "We will migrate the user_profiles table to a new schema. Old code will be updated to use the new schema."

**Problem**: What if migration fails halfway? What if new code has a bug? How do you roll back?

**Fix**: Section 8 (Migration) includes:
- **Rollback plan**: "If migration fails, we revert schema change and redeploy old code. Data in new columns ignored until next attempt. Estimated rollback time: 10 minutes."
- **Backward compatibility**: "Old code reads from old columns. New code writes to both old and new columns for 2 weeks (compatibility window), then new code switches to new columns only."
- **Testing**: "Canary rollout to 5% of users first, monitor error rates for 24 hours, then 25%, 50%, 100%."

**Check**:
- [ ] Rollback procedure is documented step-by-step with estimated recovery time
- [ ] Backward compatibility window is specified (weeks, months) and justified
- [ ] Feature flags or canary strategy is in place
- [ ] Data validation plan (how to verify migration succeeded)
- [ ] Replication lag or dual-write consistency strategy if applicable

---

### 4. "Missing Error Paths"

**Signal**: Design only describes the happy path. Failure modes are not designed.

**Bad Example**:
> "When the user submits the form, we call the payment API and charge the card."

**Problem**: What if the payment API is down? What if it times out after 30 seconds? What if the request is sent twice (duplicate charge)? No design for these.

**Fix**: Section 4.5 (Error Handling Matrix) covers all scenarios:

| Error | Detection | Response | Recovery |
|---|---|---|---|
| Payment API timeout | No response after 5 sec | Timeout exception → return 500 | Retry with exponential backoff; user retries on next request |
| Duplicate request | Idempotency key matches | Detect in DB before calling API | Return cached response from first attempt |
| Invalid card | API returns 400 | Log validation error, return to user | User corrects card and retries |

**Check**:
- [ ] Error Handling Matrix (section 4.5) includes at least: timeout, network failure, invalid input, auth failure, rate limit, 3rd party down
- [ ] Each error has: how it's detected, what happens immediately, what happens for user recovery
- [ ] Idempotency strategy for any operation that could be retried
- [ ] Circuit breaker or bulkhead for external API calls
- [ ] No mention of "this shouldn't happen" (defensive design assumes anything can fail)

---

### 5. "Scope Creep in Disguise"

**Signal**: Non-goals section is missing, empty, or vague. Features slip into scope throughout the doc.

**Bad Example**:

2. Goals & Non-Goals

Goals

• Improve user experience

Non-Goals

• (empty)

**Problem**: What does "improve" mean? What specifically is NOT included? Scope is undefined and will creep.

**Fix**: Be specific:

Goals

• Reduce checkout latency from 5 sec (p99) to < 500 ms (p99)
• Support up to 10,000 concurrent users
• Maintain 99.95% uptime SLA

Non-Goals

• We will NOT redesign the checkout UI (separate project)
• We will NOT add new payment methods (deferred to Q3)
• We will NOT implement recurring billing (separate project)
• We will NOT support 3D Secure authentication (not MVP)

**Check**:
- [ ] Goals section has measurable, specific targets (numbers, latency, throughput, uptime)
- [ ] Non-goals section explicitly lists commonly-assumed features that ARE NOT included
- [ ] No goals mentioned in any other section that aren't in section 2
- [ ] Non-goals are tested against design decisions: if feature X appears in section 4 and is not in goals, it's either a goal or should be removed

---

### Summary: How to Avoid These Anti-Patterns

1. **Start with pain**: Background and Goals sections make the "why" crystal clear before any design.
2. **Be specific**: Numbers, not adjectives. Algorithms, not buzz words. Implementation details, not hand-waving.
3. **Design for failure**: Every external dependency, every user interaction, every data transition has an error case.
4. **Plan the migration**: Rollback strategy is always included, backward compatibility is always considered, testing is always detailed.
5. **Bound the scope**: Non-goals are as important as goals. Anything not explicitly a goal should be a non-goal.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [camilooscargbaptista](https://github.com/camilooscargbaptista)
- **Source:** [camilooscargbaptista/cto-toolkit](https://github.com/camilooscargbaptista/cto-toolkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.