mohitagw15856/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

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