Technical Spec Writing

Purpose

Creates implementation-focused technical specifications that translate product requirements into concrete system designs, covering architecture, APIs, data models, and operational concerns.

When NOT to Use This Skill

• Product requirements (use prd-writing instead)
• Feature specifications (use feature-spec-writing instead)
• Implementation task breakdown (use sparc-planning instead)
• API documentation for existing code (use api-doc-writer instead)
• Reviewing tech specs (use technical-spec-reviewing instead)

Key Differences from Other Specs

| Aspect | PRD | Feature Spec | Technical Spec | |--------|-----|--------------|----------------| | Audience | Stakeholders | Engineers | Engineers | | Focus | User value | User flows | System design | | Content | User stories | Acceptance criteria | Architecture, APIs | | Detail | High-level | Edge cases | Implementation |

Workflow

Step 1: Context Gathering

Invoke check-history to understand project context.

Reference source documents:

Context to gather:
1. Parent PRD and relevant feature specs
2. Existing system architecture (what already exists)
3. Technical constraints (stack, patterns, limits)
4. Non-functional requirements (performance, scale, security)
5. Related systems and integration points

Step 2: System Overview

Write a high-level description of the proposed solution:

## System Overview

**Problem:** [What technical problem we're solving]

**Solution:** [High-level approach in 2-3 sentences]

**Key Design Decisions:**
1. [Decision 1]: [Why this approach]
2. [Decision 2]: [Why this approach]

**Scope:**
- In scope: [What this spec covers]
- Out of scope: [What's excluded, why]

Step 3: Component Architecture

Define system components and their responsibilities:

## Component Architecture

### Component Diagram

┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ Client │────▶│ API Layer │────▶│ Service │ └─────────────┘ └──────────────┘ └──────────────┘ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ Cache │ │ Database │ └──────────────┘ └──────────────┘

### Components

**[Component Name]**
- Responsibility: [What it does]
- Inputs: [What it receives]
- Outputs: [What it produces]
- Dependencies: [What it needs]

Step 4: API Design

Define APIs with request/response schemas:

## API Design

### Endpoints

#### [HTTP Method] [Path]

**Description:** [What this endpoint does]

**Authentication:** [Required/Optional, method]

**Request:**
```json
{
  "field": "type (description)",
  "nested": {
    "field": "type"
  }
}

Response (200 OK):

{
  "data": {
    "id": "string",
    "field": "type"
  },
  "meta": {
    "timestamp": "ISO8601"
  }
}

Error Responses: | Status | Code | Description | |--------|------|-------------| | 400 | INVALID_INPUT | [When this occurs] | | 401 | UNAUTHORIZED | [When this occurs] | | 404 | NOT_FOUND | [When this occurs] | | 500 | INTERNAL_ERROR | [When this occurs] |

### Step 5: Data Model

Define data structures and persistence:

```markdown
## Data Model

### Entity: [Name]

**Table:** `table_name`

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PK | Primary identifier |
| field | VARCHAR(255) | NOT NULL | Description |
| status | ENUM | DEFAULT 'active' | Status enum |
| created_at | TIMESTAMP | NOT NULL | Creation time |

**Indexes:**
- `idx_field_status` on (field, status) - for [query type]

**Relationships:**
- Has many: [Related entities]
- Belongs to: [Parent entities]

### Entity Diagram

┌───────────────┐ ┌───────────────┐ │ Entity A │───────│ Entity B │ ├───────────────┤ 1:N ├───────────────┤ │ id (PK) │ │ id (PK) │ │ field │ │ entity_a_id │ └───────────────┘ └───────────────┘

Step 6: Implementation Approach

Describe algorithms and key implementation details:

## Implementation Approach

### Algorithm: [Name]

**Purpose:** [What it accomplishes]

**Pseudocode:**

function processRequest(input): 1. Validate input 2. Fetch dependencies from cache/db 3. Apply business logic 4. Persist changes 5. Emit events 6. Return response

**Key Considerations:**
- [Consideration 1 and how we handle it]
- [Consideration 2 and how we handle it]

### Design Patterns Used

| Pattern | Where Used | Why |
|---------|-----------|-----|
| Repository | Data access | Decouple from DB |
| Factory | Object creation | Complex instantiation |
| Observer | Events | Loose coupling |

Step 7: Testing Strategy

Define testing approach:

## Testing Strategy

### Unit Tests
- [Component]: [What to test]
- [Component]: [What to test]
- Coverage target: 90%+

### Integration Tests
- API endpoints: Happy path + error cases
- Database operations: CRUD + edge cases
- External services: Mock + contract tests

### E2E Tests
- [Critical flow 1]
- [Critical flow 2]

### Performance Tests
- Load test: [Scenario and expected results]
- Stress test: [Breaking point identification]

Step 8: Performance Considerations

Define performance targets and optimization:

## Performance Considerations

### Targets

| Metric | Target | Measurement |
|--------|--------|-------------|
| API Response Time | < 200ms p95 | APM |
| Database Query | < 50ms p95 | Query logging |
| Throughput | 1000 req/s | Load testing |

### Optimization Strategies

**Caching:**
- What: [Data to cache]
- Where: [Cache location]
- TTL: [Duration]
- Invalidation: [Strategy]

**Database:**
- Indexes: [Key indexes needed]
- Query optimization: [Specific optimizations]
- Connection pooling: [Pool size]

**Async Processing:**
- [What to make async and why]

Step 9: Security Considerations

Address security concerns:

## Security Considerations

### Authentication
- Method: [JWT, OAuth, etc.]
- Token handling: [How tokens are managed]

### Authorization
- Model: [RBAC, ABAC, etc.]
- Checks: [Where authorization is enforced]

### Data Protection
- At rest: [Encryption method]
- In transit: [TLS version]
- Sensitive fields: [Which fields, how protected]

### Input Validation
- [Input type]: [Validation rules]

### Security Checklist
- [ ] OWASP Top 10 addressed
- [ ] Input validation on all endpoints
- [ ] SQL injection prevention
- [ ] XSS prevention
- [ ] CSRF protection
- [ ] Rate limiting
- [ ] Audit logging

Step 10: Migration & Rollback

Plan for deployment:

## Migration & Rollback

### Migration Steps
1. [Step with validation]
2. [Step with validation]
3. [Step with validation]

### Database Migrations
```sql
-- Migration: [name]
ALTER TABLE ...

Rollback Plan

1. [Rollback step]
2. [Rollback step]

Feature Flags

| Flag | Purpose | Default | |------|---------|---------| | [name] | [control what] | Off |

Rollout Plan

• Phase 1: Internal testing (0%)
• Phase 2: Beta users (5%)
• Phase 3: Gradual (25%, 50%, 100%)

### Step 11: Output Generation

Generate the technical spec using TEMPLATE.md. Verify:

- [ ] System overview is clear
- [ ] Component architecture defined
- [ ] APIs fully specified with schemas
- [ ] Data model complete
- [ ] Implementation approach clear
- [ ] Testing strategy comprehensive
- [ ] Performance targets defined
- [ ] Security considerations addressed
- [ ] Migration plan included

## Examples

### Example 1: E-Commerce - Shipping Rate API

**System Overview:**

Problem: Need real-time shipping rate calculation that integrates with multiple carriers without impacting product page load time.

Solution: Create async shipping rate service with carrier abstraction layer, caching, and fallback strategies.

Key Decisions:

1. Async API: Non-blocking for product page
2. Carrier abstraction: Swap carriers without code changes
3. Cache-first: Reduce API calls, improve latency

**Component Architecture:**

┌────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Product │───▶│ Shipping Rate │───▶│ Carrier Gateway │ │ Page │ │ Service │ │ (Abstraction) │ └────────────┘ └─────────────────┘ └─────────────────┘ │ │ ▼ ▼ ┌─────────────┐ ┌──────────────────────┐ │ Redis │ │ UPS / FedEx / USPS │ │ (Cache) │ │ (External) │ └─────────────┘ └──────────────────────┘

**API Design:**

POST /api/shipping/rates

Request: { "destination_zip": "94102", "items": [{ "sku": "ABC123", "quantity": 2, "weight_oz": 8 }] }

Response (200): { "rates": [ { "carrier": "UPS", "service": "Ground", "price": 5.99, "days": 5 }, { "carrier": "FedEx", "service": "Express", "price": 12.99, "days": 2 } ], "cached": false, "calculated_at": "2024-01-15T10:30:00Z" }

---

### Example 2: SaaS - Permission System

**System Overview:**

Problem: Need granular role-based access control that supports custom roles, permission inheritance, and audit logging.

Solution: RBAC system with permission groups, role hierarchy, and event-sourced audit trail.

Key Decisions:

1. Permission groups: Organize related permissions
2. Role hierarchy: Support inheritance
3. Event sourcing: Complete audit history

**Data Model:**

┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ Role │───▶│ Permission │◀───│ PermissionGroup │ ├─────────────┤ N:M├─────────────┤ ├─────────────────┤ │ id │ │ id │ │ id │ │ name │ │ name │ │ name │ │ org_id │ │ resource │ │ description │ │ parent_id │ │ action │ └─────────────────┘ └─────────────┘ └─────────────┘

┌─────────────┐ ┌─────────────────┐ │ User │───▶│ UserRoleAssign │ └─────────────┘ 1:N└─────────────────┘

---

### Example 3: Fintech - Transaction Alert System

**System Overview:**

Problem: Deliver real-time transaction alerts to users within seconds of transaction processing.

Solution: Event-driven architecture using message queue for reliable delivery across push, SMS, and email channels.

Key Decisions:

1. Event-driven: Decouple from transaction processing
2. Multi-channel: Push, SMS, email with preferences
3. At-least-once: Ensure delivery with deduplication

**Component Architecture:**

┌───────────────┐ ┌─────────────────┐ ┌───────────────┐ │ Transaction │───▶│ Message Queue │───▶│ Alert │ │ Service │ │ (Kafka) │ │ Service │ └───────────────┘ └─────────────────┘ └───────────────┘ │ ┌────────────────────────────┼────────────┐ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ Push │ │ SMS │ │ Email │ │ Service │ │ Service │ │ Service │ └───────────┘ └───────────┘ └───────────┘

**Performance Targets:**
| Metric | Target |
|--------|--------|
| Alert delivery latency | < 5 seconds from transaction |
| Throughput | 10,000 alerts/second |
| Availability | 99.99% |

## Anti-Patterns to Avoid

### Missing Rationale

❌ "Use Redis for caching" ✅ "Use Redis for caching (sub-ms latency needed, 100K reads/sec expected)"

### Vague Performance Targets

❌ "System should be fast" ✅ "API response < 200ms p95, database query < 50ms p95"

### No Error Handling

❌ Only happy path API responses ✅ Full error response catalog with codes and handling

### Implementation in Tech Spec

❌ Including actual code implementation ✅ Pseudocode and design patterns, leaving implementation to engineers

## Integration with Other Skills

**Receives From:**
- `prd-writing` - High-level requirements
- `feature-spec-writing` - Detailed feature requirements

**Works With:**
- `technical-spec-reviewing` - Review technical specs
- `api-doc-writer` - Document APIs after implementation

**Leads To:**
- `sparc-planning` - Implementation task breakdown

## Output Validation

Before finalizing:

- [ ] System overview explains the approach clearly
- [ ] All components have defined responsibilities
- [ ] APIs have complete request/response schemas
- [ ] Data model includes all entities and relationships
- [ ] Performance targets are specific and measurable
- [ ] Security considerations are addressed
- [ ] Migration and rollback plan included
- [ ] Open questions documented

## Resources

- See TEMPLATE.md for complete technical spec format
- See REFERENCE.md for architecture patterns and guidance


---

## Related Agent

For comprehensive specification guidance that coordinates this and other spec skills, use the **`specification-architect`** agent.