Technical Spec Template Skill
Write technical specifications that engineers actually read — clear problem framing, unambiguous requirements, explicit decisions, and documented trade-offs.
Required Inputs
Ask the user for these if not provided:
- Feature or system description (what needs to be specced)
- Related PRD or product brief (if available)
- Engineering reviewers (whose sign-off is needed)
- Known constraints (technical limitations, security requirements, performance targets)
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:
-- 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
Deeper Materials
This skill ships with support files — use them when they are available:
references/spec-decisions.md — What a Spec Is For: Decisions, Alternatives, and the Blast Radius. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.templates/spec-skeleton.md — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.
Scoring Rubric (0–40)
Score any output of this skill before handing it over; 32+ is ship-quality.
| Dimension |
0 |
5 |
10 |
| Problem framing |
Problem statement is the solution restated ("we need a queue"), or missing; no non-goals |
Problem stated but with solution language leaking in; non-goals present but generic ("out of scope: everything else") |
Problem described in user/business terms with numbers, independent of any solution; goals measurable; ≥2 non-goals that shut down real scope assumptions |
| Decision documentation |
One approach, no alternatives — a design description, not a decision record |
Alternatives table exists but strawmanned (cons-only options nobody argued for); rejection reasons are taste, not evidence |
≥2 genuine alternatives with honest pros, evidence-based rejection reasons, recorded dissent where it exists, and revisit triggers for contested calls |
| Security & privacy depth |
Section skipped or "N/A" on a feature that touches user data |
Boilerplate answers (encrypt at rest/in transit) with no analysis of this feature's specific data exposure |
Data touched is enumerated, the design's single largest privacy risk is named, authn/authz/compliance addressed concretely, and unresolved risks visibly gate approval |
| Operational readiness |
No testing plan, rollout plan, or rollback trigger; open questions absent or all "TBD" |
Testing and rollout sketched but rollback is untested intent; some open questions lack owners or dates |
Tests cover the tricky edge cases, rollout is staged with progress criteria, rollback trigger is concrete (and doesn't strand data), and every open question has a named owner and due date |
Quality Checks
Anti-Patterns
1---2name: technical-spec-template3description: Create 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. Produces a complete spec with problem statement, proposed solution, data model, API design, alternatives considered, security considerations, testing plan, and rollout strategy.4---5
6# Technical Spec Template Skill
7
8Write technical specifications that engineers actually read — clear problem framing, unambiguous requirements, explicit decisions, and documented trade-offs.
9
10## Required Inputs
11
12Ask the user for these if not provided:
13- **Feature or system description** (what needs to be specced)
14- **Related PRD or product brief** (if available)
15- **Engineering reviewers** (whose sign-off is needed)
16- **Known constraints** (technical limitations, security requirements, performance targets)
17
18## When to Write a Tech Spec
19
20Write a tech spec when:
21- The feature requires changes to 2+ systems
22- There are significant architectural decisions to make
23- More than one engineer will work on the implementation
24- The feature has security, privacy, or compliance implications
25- Estimated effort is >5 story points
26
27Skip the spec for trivial bug fixes or 1-2 hour changes.
28
29---
30
31## Technical Spec Output Format
32
33### Technical Specification — [Feature Name]
34
35**Author:** [Name]
36**Status:** Draft | In Review | Approved | Implemented
37**Created:** [Date] | **Last Updated:** [Date]
38**Reviewers:** [Eng Lead, Architect, PM, Security if needed]
39**Related PRD:** [Link] | **Jira Epic:** [Link]
40
41---
42
43#### 1. Problem Statement
44> [2–3 sentences. What problem are we solving and why now? No solution language here.]
45
46#### 2. Goals & Non-Goals
47
48**Goals (in scope):**
49- [Specific, measurable outcome]
50- [Specific, measurable outcome]
51
52**Non-Goals (explicitly out of scope):**
53- [What this spec does NOT cover]
54- [Common assumption to shut down early]
55
56#### 3. Background & Context
57[Any prior art, related systems, or context engineers need to understand the decision space. Link to previous specs, ADRs, or research.]
58
59#### 4. Proposed Solution
60
61**High-Level Approach:**
62[2–4 sentences describing the chosen solution. Why this approach vs alternatives?]
63
64**System Architecture Diagram:**
65[Describe or embed: which services are involved, how data flows, what APIs are called]
66
67**Data Model Changes:**
68```sql
69-- New tables or schema changes
70[Include DDL or schema definition]
71```
72
73**API Design:**
74```
75[Endpoint] [Method]
76Request: { [fields and types] }
77Response: { [fields and types] }
78Error codes: [list]
79```
80
81**Key Implementation Details:**
82- [Important technical constraint or approach]
83- [Edge case handling]
84- [Third-party dependency and version]
85
86#### 5. Alternative Approaches Considered
87
88| Option | Pros | Cons | Why Rejected |
89|---|---|---|---|
90| [Alt 1] | [Benefits] | [Drawbacks] | [Reason not chosen] |
91| [Alt 2] | [Benefits] | [Drawbacks] | [Reason not chosen] |
92
93#### 6. Security & Privacy Considerations
94- Data stored: [What PII or sensitive data is involved]
95- Authentication: [How is access controlled]
96- Authorisation: [What permissions are required]
97- Encryption: [At rest / in transit requirements]
98- Compliance implications: [GDPR, SOC2, etc. if relevant]
99
100#### 7. Performance & Scalability
101- Expected load: [Requests/second, data volume]
102- Latency requirements: [P50 / P95 targets]
103- Caching strategy: [If applicable]
104- Database indexing: [New indexes required]
105- Known bottlenecks: [Where to watch]
106
107#### 8. Testing Plan
108- Unit tests: [Key scenarios to cover]
109- Integration tests: [System boundaries to test]
110- Load tests: [If performance-critical]
111- Edge cases: [Known tricky scenarios]
112- Rollback plan: [How to revert if something goes wrong]
113
114#### 9. Rollout Plan
115- Feature flag: [Yes / No — name of flag]
116- Rollout stages: [% of users at each stage]
117- Monitoring: [Metrics and alerts to set up]
118- Success criteria to progress rollout: [What needs to be true]
119- Rollback trigger: [What would cause immediate rollback]
120
121#### 10. Open Questions
122| Question | Owner | Due Date | Resolution |
123|---|---|---|---|
124| [Unresolved question] | [Name] | [Date] | [Pending] |
125
126#### 11. Implementation Timeline (Rough)
127| Phase | Work | Estimated Effort |
128|---|---|---|
129| [Phase 1] | [What gets built] | [X days/points] |
130| [Phase 2] | [What gets built] | [X days/points] |
131| Total | | [X story points] |
132
133---
134
135## Guidelines
136
137- The spec is a decision record, not a task list — document *why* decisions were made
138- All open questions must have an owner and due date
139- Security and privacy sections are never optional for features that touch user data
140- Recommend async review: engineers read first, then a 30-minute sync to resolve questions
141- Keep the spec updated as implementation progresses — stale specs are worse than no specs
142
143## Deeper Materials
144
145This skill ships with support files — use them when they are available:
146
147- **`references/spec-decisions.md`** — What a Spec Is For: Decisions, Alternatives, and the Blast Radius. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
148- **`templates/spec-skeleton.md`** — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.
149
150## Scoring Rubric (0–40)
151
152Score any output of this skill before handing it over; 32+ is ship-quality.
153
154| Dimension | 0 | 5 | 10 |
155|---|---|---|---|
156| Problem framing | Problem statement is the solution restated ("we need a queue"), or missing; no non-goals | Problem stated but with solution language leaking in; non-goals present but generic ("out of scope: everything else") | Problem described in user/business terms with numbers, independent of any solution; goals measurable; ≥2 non-goals that shut down real scope assumptions |
157| Decision documentation | One approach, no alternatives — a design description, not a decision record | Alternatives table exists but strawmanned (cons-only options nobody argued for); rejection reasons are taste, not evidence | ≥2 genuine alternatives with honest pros, evidence-based rejection reasons, recorded dissent where it exists, and revisit triggers for contested calls |
158| Security & privacy depth | Section skipped or "N/A" on a feature that touches user data | Boilerplate answers (encrypt at rest/in transit) with no analysis of this feature's specific data exposure | Data touched is enumerated, the design's single largest privacy risk is named, authn/authz/compliance addressed concretely, and unresolved risks visibly gate approval |
159| Operational readiness | No testing plan, rollout plan, or rollback trigger; open questions absent or all "TBD" | Testing and rollout sketched but rollback is untested intent; some open questions lack owners or dates | Tests cover the tricky edge cases, rollout is staged with progress criteria, rollback trigger is concrete (and doesn't strand data), and every open question has a named owner and due date |
160
161## Quality Checks
162
163- [ ] Problem statement contains no solution language
164- [ ] Non-goals explicitly list at least 2 things that might be assumed in scope
165- [ ] At least 2 alternative approaches are documented with reasons for rejection
166- [ ] Security and privacy section is completed for any feature touching user data
167- [ ] All open questions have a named owner and due date (not "TBD")
168
169## Anti-Patterns
170
171- [ ] Do not include solution language in the problem statement — the problem must be described independently of the proposed solution
172- [ ] Do not omit alternatives considered — a spec that considers only one approach has not been properly evaluated
173- [ ] Do not leave open questions as "TBD" without a named owner and due date — unresolved questions are blockers
174- [ ] Do not skip security and privacy sections for any feature that touches user data
175- [ ] Do not write a non-goals section that is empty — always list at least two things that might be assumed in scope
Mohit Aggarwal