mohitagw15856
134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
---
|
||
name: technical-spec-template
|
||
description: Creates structured technical specification documents that bridge product requirements and engineering implementation. Use when writing a tech spec, engineering spec, system design doc, or API specification. Triggers on "technical spec", "tech spec", "engineering spec", "system design doc", "API spec", "implementation spec".
|
||
---
|
||
|
||
# Technical Spec Template Skill
|
||
|
||
Write technical specifications that engineers actually read — clear problem framing, unambiguous requirements, explicit decisions, and documented trade-offs.
|
||
|
||
## When to Write a Tech Spec
|
||
|
||
Write a tech spec when:
|
||
- The feature requires changes to 2+ systems
|
||
- There are significant architectural decisions to make
|
||
- More than one engineer will work on the implementation
|
||
- The feature has security, privacy, or compliance implications
|
||
- Estimated effort is >5 story points
|
||
|
||
Skip the spec for trivial bug fixes or 1-2 hour changes.
|
||
|
||
---
|
||
|
||
## Technical Spec Output Format
|
||
|
||
### Technical Specification — [Feature Name]
|
||
|
||
**Author:** [Name]
|
||
**Status:** Draft | In Review | Approved | Implemented
|
||
**Created:** [Date] | **Last Updated:** [Date]
|
||
**Reviewers:** [Eng Lead, Architect, PM, Security if needed]
|
||
**Related PRD:** [Link] | **Jira Epic:** [Link]
|
||
|
||
---
|
||
|
||
#### 1. Problem Statement
|
||
> [2–3 sentences. What problem are we solving and why now? No solution language here.]
|
||
|
||
#### 2. Goals & Non-Goals
|
||
|
||
**Goals (in scope):**
|
||
- [Specific, measurable outcome]
|
||
- [Specific, measurable outcome]
|
||
|
||
**Non-Goals (explicitly out of scope):**
|
||
- [What this spec does NOT cover]
|
||
- [Common assumption to shut down early]
|
||
|
||
#### 3. Background & Context
|
||
[Any prior art, related systems, or context engineers need to understand the decision space. Link to previous specs, ADRs, or research.]
|
||
|
||
#### 4. Proposed Solution
|
||
|
||
**High-Level Approach:**
|
||
[2–4 sentences describing the chosen solution. Why this approach vs alternatives?]
|
||
|
||
**System Architecture Diagram:**
|
||
[Describe or embed: which services are involved, how data flows, what APIs are called]
|
||
|
||
**Data Model Changes:**
|
||
```sql
|
||
-- New tables or schema changes
|
||
[Include DDL or schema definition]
|
||
```
|
||
|
||
**API Design:**
|
||
```
|
||
[Endpoint] [Method]
|
||
Request: { [fields and types] }
|
||
Response: { [fields and types] }
|
||
Error codes: [list]
|
||
```
|
||
|
||
**Key Implementation Details:**
|
||
- [Important technical constraint or approach]
|
||
- [Edge case handling]
|
||
- [Third-party dependency and version]
|
||
|
||
#### 5. Alternative Approaches Considered
|
||
|
||
| Option | Pros | Cons | Why Rejected |
|
||
|---|---|---|---|
|
||
| [Alt 1] | [Benefits] | [Drawbacks] | [Reason not chosen] |
|
||
| [Alt 2] | [Benefits] | [Drawbacks] | [Reason not chosen] |
|
||
|
||
#### 6. Security & Privacy Considerations
|
||
- Data stored: [What PII or sensitive data is involved]
|
||
- Authentication: [How is access controlled]
|
||
- Authorisation: [What permissions are required]
|
||
- Encryption: [At rest / in transit requirements]
|
||
- Compliance implications: [GDPR, SOC2, etc. if relevant]
|
||
|
||
#### 7. Performance & Scalability
|
||
- Expected load: [Requests/second, data volume]
|
||
- Latency requirements: [P50 / P95 targets]
|
||
- Caching strategy: [If applicable]
|
||
- Database indexing: [New indexes required]
|
||
- Known bottlenecks: [Where to watch]
|
||
|
||
#### 8. Testing Plan
|
||
- Unit tests: [Key scenarios to cover]
|
||
- Integration tests: [System boundaries to test]
|
||
- Load tests: [If performance-critical]
|
||
- Edge cases: [Known tricky scenarios]
|
||
- Rollback plan: [How to revert if something goes wrong]
|
||
|
||
#### 9. Rollout Plan
|
||
- Feature flag: [Yes / No — name of flag]
|
||
- Rollout stages: [% of users at each stage]
|
||
- Monitoring: [Metrics and alerts to set up]
|
||
- Success criteria to progress rollout: [What needs to be true]
|
||
- Rollback trigger: [What would cause immediate rollback]
|
||
|
||
#### 10. Open Questions
|
||
| Question | Owner | Due Date | Resolution |
|
||
|---|---|---|---|
|
||
| [Unresolved question] | [Name] | [Date] | [Pending] |
|
||
|
||
#### 11. Implementation Timeline (Rough)
|
||
| Phase | Work | Estimated Effort |
|
||
|---|---|---|
|
||
| [Phase 1] | [What gets built] | [X days/points] |
|
||
| [Phase 2] | [What gets built] | [X days/points] |
|
||
| Total | | [X story points] |
|
||
|
||
---
|
||
|
||
## Guidelines
|
||
|
||
- The spec is a decision record, not a task list — document *why* decisions were made
|
||
- All open questions must have an owner and due date
|
||
- Security and privacy sections are never optional for features that touch user data
|
||
- Recommend async review: engineers read first, then a 30-minute sync to resolve questions
|
||
- Keep the spec updated as implementation progresses — stale specs are worse than no specs
|