technical-spec-template

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

• [ ] 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