Technical Specification Template

Write a tech spec when the work touches multiple services, requires data model changes, introduces new external dependencies, or will take more than one sprint to implement. If the change is isolated to a single service with a well-understood pattern, a detailed ticket description is sufficient. When in doubt, ask your tech lead. The [Technical PM Handbook](/technical-pm-guide) covers how to calibrate documentation depth to project complexity.

The engineer who will lead the implementation. The PM provides the PRD and is available for questions, but the tech spec is an engineering document. The PM should review it to confirm the spec matches the product requirements, but they should not be the author.

Detailed enough that frontend and backend engineers can work in parallel without blocking each other. Include request/response schemas with field types, required/optional annotations, status codes, and error formats. You do not need to document every possible validation error, but cover the happy path and the 3-4 most common failure modes.

Include a timeline with milestones, not day-level estimates for individual tasks. The spec timeline covers major phases (design, implementation, testing, rollout) and their dependencies. Sprint-level task breakdowns belong in the project management tool, not the spec.

Use the Open Questions section to document disagreements with the specific options being debated. Set a decision deadline and an owner. If the team cannot resolve the question within 48 hours, escalate to the tech lead or engineering manager for a tiebreaker. Do not let open questions block the rest of the spec from being finalized. ---