Initial commit

skills/spec-author/templates/design-document.md

@@ -0,0 +1,221 @@
+### Design Document
+
+# <!-- Title and ID, e.g., #[DESIGN-001] Microservices Architecture for User Service -->
+
+Type: <!-- Architecture | System Design | RFC | Technology Choice -->
+Status: <!-- Draft | Under Review | Accepted | Rejected -->
+Version: <!-- e.g., 1.0.0 -->
+
+## Executive Summary
+
+<!-- 3-4 sentences: What problem does this solve? What's the proposed solution? What are the key tradeoffs? -->
+
+## Problem Statement
+
+<!-- Describe the current state, limitations, and impact. Why are existing solutions insufficient? -->
+
+## Goals & Success Criteria
+
+### Primary Goals
+- **Goal 1**: <!-- Specific, measurable objective -->
+- **Goal 2**: <!-- Specific, measurable objective -->
+- **Goal 3**: <!-- Specific, measurable objective -->
+
+### Success Criteria
+1. <!-- Measurable criterion with target metrics -->
+2. <!-- Measurable criterion with target metrics -->
+3. <!-- Measurable criterion with target metrics -->
+
+## Context & Background
+
+<!-- Why now? What triggered this decision? What constraints exist? Historical context if relevant. -->
+
+## Proposed Solution
+
+### High-Level Overview
+
+<!-- Architecture diagram or ASCII art showing major components and data flow -->
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │
+       ├─→ [API Gateway]
+       │         │
+       ├─→ [Service Layer]
+       │    ├─ Service A
+       │    └─ Service B
+       │
+       └─→ [Data Layer]
+            ├─ Database
+            └─ Cache
+```
+
+<!-- Brief narrative: How do components work together? What's the overall approach? -->
+
+### Architecture Components
+
+#### <!-- Component Name -->
+- **Purpose**: <!-- What this component does -->
+- **Technology**: <!-- Stack choice and version -->
+- **Key Responsibilities**: <!-- Primary functions -->
+- **Interactions**: <!-- How it connects with other components -->
+
+#### <!-- Component Name -->
+- **Purpose**: <!-- What this component does -->
+- **Technology**: <!-- Stack choice and version -->
+- **Key Responsibilities**: <!-- Primary functions -->
+- **Interactions**: <!-- How it connects with other components -->
+
+### Design Decisions
+
+#### Decision 1: <!-- Decision Title -->
+- **Decision**: <!-- What was chosen -->
+- **Rationale**: <!-- Why this choice over alternatives -->
+- **Alternatives Considered**: <!-- Briefly list other options and why they weren't chosen -->
+- **Impact**: <!-- Key consequences of this decision -->
+
+#### Decision 2: <!-- Decision Title -->
+- **Decision**: <!-- What was chosen -->
+- **Rationale**: <!-- Why this choice over alternatives -->
+- **Alternatives Considered**: <!-- Briefly list other options and why they weren't chosen -->
+- **Impact**: <!-- Key consequences of this decision -->
+
+### Technology Stack
+
+**Language & Runtime**
+- <!-- Technology, version, and rationale -->
+
+**Data Layer**
+- <!-- Primary database/storage, version, and rationale -->
+- <!-- Cache layer, version, and rationale -->
+
+**Infrastructure**
+- <!-- Hosting/cloud platform and rationale -->
+- <!-- Container/orchestration technology if applicable -->
+
+**Key Libraries/Frameworks**
+- <!-- Critical dependencies with versions -->
+
+### Data Model & Storage
+
+<!-- Reference data specification or provide high-level overview -->
+
+**Storage Strategy**
+- **Primary Database**: <!-- Choice and structure -->
+- **Caching**: <!-- Strategy and technology -->
+- **Data Retention**: <!-- Archival and cleanup policies -->
+
+<!-- Optionally include simplified schema or entity relationships -->
+
+### API & Integration Points
+
+<!-- Reference API specification or list key endpoints and integrations -->
+
+**External Dependencies**
+- Integrates with <!-- Service/API name --> for <!-- purpose -->
+- Consumes events from <!-- Service/API name -->
+- Publishes events to <!-- Service/API name -->
+
+**Key Endpoints** (or reference API spec)
+- <!-- HTTP method and path -->: <!-- Purpose -->
+- <!-- HTTP method and path -->: <!-- Purpose -->
+
+## Trade-offs
+
+### Accepting
+- <!-- Cost, complexity, or limitation we're accepting -->
+- <!-- Technical debt or constraint we're taking on -->
+- <!-- Performance or feature tradeoff -->
+
+### Gaining
+- <!-- Primary benefit we're achieving -->
+- <!-- Problem we're solving -->
+- <!-- Capability we're enabling -->
+
+## Implementation
+
+<!-- Reference implementation plan or outline high-level phases -->
+
+**Approach**: <!-- Sequential rollout, phased migration, parallel development, etc. -->
+
+**Phases**:
+1. **Phase 1**: <!-- Description, key deliverables -->
+2. **Phase 2**: <!-- Description, key deliverables -->
+3. **Phase 3**: <!-- Description, key deliverables -->
+
+**Migration Strategy** (if applicable):
+- <!-- How existing systems/data will be transitioned -->
+
+See [Plan Specification](#) for detailed implementation roadmap.
+
+## Performance & Scalability
+
+### Performance Targets
+- **Latency**: <!-- e.g., < 100ms p95, < 200ms p99 -->
+- **Throughput**: <!-- e.g., 1000 requests/second -->
+- **Availability**: <!-- e.g., 99.9% uptime -->
+
+### Scalability Strategy
+- **Scaling Approach**: <!-- Horizontal/vertical, stateless design, etc. -->
+- **Bottlenecks**: <!-- Known limitations and mitigation strategies -->
+- **Auto-scaling**: <!-- Triggers, thresholds, and scaling policies -->
+
+### Monitoring & Observability
+- **Metrics**: <!-- Key metrics to track -->
+- **Alerting**: <!-- Critical alerts and thresholds -->
+- **Logging**: <!-- Logging strategy and aggregation -->
+
+## Security
+
+**Authentication**
+- <!-- Method: JWT, OAuth, API keys, etc. -->
+
+**Authorization**
+- <!-- Access control approach: RBAC, ABAC, etc. -->
+
+**Data Protection**
+- **Encryption at Rest**: <!-- Method and key management -->
+- **Encryption in Transit**: <!-- TLS/SSL configuration -->
+- **PII Handling**: <!-- Sensitive data protection approach -->
+
+**Secrets Management**
+- <!-- How secrets, credentials, and keys are managed -->
+
+**Compliance**
+- <!-- Relevant standards: GDPR, SOC2, HIPAA, etc. -->
+
+## Dependencies & Assumptions
+
+### Dependencies
+- <!-- External service or system dependency and impact if unavailable -->
+- <!-- Team or resource dependency -->
+- <!-- Third-party library or platform dependency -->
+
+### Assumptions
+- <!-- Key assumption that must hold true for this design to work -->
+- <!-- Assumption about scale, usage patterns, or constraints -->
+- <!-- Assumption about external systems or future capabilities -->
+
+## Open Questions
+
+<!-- Questions that need resolution before or during implementation -->
+
+- [ ] <!-- Question or decision to be made --> - **Status**: <!-- Under investigation, blocked, etc. -->
+- [ ] <!-- Question or decision to be made --> - **Status**: <!-- Under investigation, blocked, etc. -->
+- [ ] <!-- Deferred decision with rationale for deferral -->
+
+## Approvals
+
+**Technical Review**
+- <!-- Name, Role -->
+
+**Architecture Review**
+- <!-- Name, Role -->
+
+**Security Review**
+- <!-- Name, Role -->
+
+**Approved By**
+- <!-- Name, Role -->