Technical Spec Template Skill

Write technical specifications that engineers actually read — clear problem framing, unambiguous requirements, explicit decisions, and documented trade-offs.

Required Inputs

Work from what is given. If any of these is missing, still produce the complete output: fill each gap with a reasonable assumption marked (assumed, confirm) and list those assumptions at the end. Ask a question first only when the core subject itself is missing (there is nothing to write about).

• 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

#### 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

#### 11. Implementation Timeline (Rough)

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

Deeper Materials

This skill ships with support files — use them when they are available:

• `references/spec-decisions.md` — What a Spec Is For: Decisions, Alternatives, and the Blast Radius. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
• `templates/spec-skeleton.md` — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.

Scoring Rubric (0–40)

Score any output of this skill before handing it over; 32+ is ship-quality.

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

Example Trigger Phrases

• "Write a tech spec."
• "Write the engineering spec for this feature."
• "Write a system design doc."
• "Write an API specification."