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]

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

Quality Checks

Problem statement contains no solution language
Non-goals explicitly list at least 2 things that might be assumed in scope
At least 2 alternative approaches are documented with reasons for rejection
Security and privacy section is completed for any feature touching user data
All open questions have a named owner and due date (not "TBD")

Anti-Patterns

Do not include solution language in the problem statement — the problem must be described independently of the proposed solution
Do not omit alternatives considered — a spec that considers only one approach has not been properly evaluated
Do not leave open questions as "TBD" without a named owner and due date — unresolved questions are blockers
Do not skip security and privacy sections for any feature that touches user data
Do not write a non-goals section that is empty — always list at least two things that might be assumed in scope

Technical Spec Template