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
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-template-23description: 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---56# Technical Spec Template Skill78Write technical specifications that engineers actually read — clear problem framing, unambiguous requirements, explicit decisions, and documented trade-offs.910## Required Inputs1112Ask 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)1718## When to Write a Tech Spec1920Write a tech spec when:21- The feature requires changes to 2+ systems22- There are significant architectural decisions to make23- More than one engineer will work on the implementation24- The feature has security, privacy, or compliance implications25- Estimated effort is >5 story points2627Skip the spec for trivial bug fixes or 1-2 hour changes.2829---3031## Technical Spec Output Format3233### Technical Specification — [Feature Name]3435**Author:** [Name]36**Status:** Draft | In Review | Approved | Implemented37**Created:** [Date] | **Last Updated:** [Date]38**Reviewers:** [Eng Lead, Architect, PM, Security if needed]39**Related PRD:** [Link] | **Jira Epic:** [Link]4041---4243#### 1. Problem Statement44> [2–3 sentences. What problem are we solving and why now? No solution language here.]4546#### 2. Goals & Non-Goals4748**Goals (in scope):**49- [Specific, measurable outcome]50- [Specific, measurable outcome]5152**Non-Goals (explicitly out of scope):**53- [What this spec does NOT cover]54- [Common assumption to shut down early]5556#### 3. Background & Context57[Any prior art, related systems, or context engineers need to understand the decision space. Link to previous specs, ADRs, or research.]5859#### 4. Proposed Solution6061**High-Level Approach:**62[2–4 sentences describing the chosen solution. Why this approach vs alternatives?]6364**System Architecture Diagram:**65[Describe or embed: which services are involved, how data flows, what APIs are called]6667**Data Model Changes:**68```sql69-- New tables or schema changes70[Include DDL or schema definition]71```7273**API Design:**74```75[Endpoint] [Method]76Request: { [fields and types] }77Response: { [fields and types] }78Error codes: [list]79```8081**Key Implementation Details:**82- [Important technical constraint or approach]83- [Edge case handling]84- [Third-party dependency and version]8586#### 5. Alternative Approaches Considered8788| Option | Pros | Cons | Why Rejected |89|---|---|---|---|90| [Alt 1] | [Benefits] | [Drawbacks] | [Reason not chosen] |91| [Alt 2] | [Benefits] | [Drawbacks] | [Reason not chosen] |9293#### 6. Security & Privacy Considerations94- 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]99100#### 7. Performance & Scalability101- 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]106107#### 8. Testing Plan108- 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]113114#### 9. Rollout Plan115- 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]120121#### 10. Open Questions122| Question | Owner | Due Date | Resolution |123|---|---|---|---|124| [Unresolved question] | [Name] | [Date] | [Pending] |125126#### 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] |132133---134135## Guidelines136137- The spec is a decision record, not a task list — document *why* decisions were made138- All open questions must have an owner and due date139- Security and privacy sections are never optional for features that touch user data140- Recommend async review: engineers read first, then a 30-minute sync to resolve questions141- Keep the spec updated as implementation progresses — stale specs are worse than no specs142143## Scoring Rubric (0–40)144145Score any output of this skill before handing it over; 32+ is ship-quality.146147| Dimension | 0 | 5 | 10 |148|---|---|---|---|149| 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 |150| 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 |151| 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 |152| 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 |153154## Quality Checks155156- [ ] Problem statement contains no solution language157- [ ] Non-goals explicitly list at least 2 things that might be assumed in scope158- [ ] At least 2 alternative approaches are documented with reasons for rejection159- [ ] Security and privacy section is completed for any feature touching user data160- [ ] All open questions have a named owner and due date (not "TBD")161162## Anti-Patterns163164- [ ] Do not include solution language in the problem statement — the problem must be described independently of the proposed solution165- [ ] Do not omit alternatives considered — a spec that considers only one approach has not been properly evaluated166- [ ] Do not leave open questions as "TBD" without a named owner and due date — unresolved questions are blockers167- [ ] Do not skip security and privacy sections for any feature that touches user data168- [ ] Do not write a non-goals section that is empty — always list at least two things that might be assumed in scope
gabrielmoreira