Technical Specification Template - Plannotator

Use a technical specification when behavior and design must remain understandable after the initial implementation. It tells implementers what must be true and gives reviewers enough detail to challenge the design.

# [System or feature] technical specification

Status: Draft | Accepted | Implemented | Superseded
Owners: [People or team]
Last reviewed: [Date]

## Summary
[The useful answer in two or three sentences.]

## Problem and users
[Who needs what, and what evidence establishes the problem.]

## Requirements
- R1. [Observable required behavior]
- R2. [Observable required behavior]

## Non-goals
- [Behavior or system deliberately excluded]

## Design
[Components, responsibilities, data flow, and important boundaries.]

## Interfaces and data
[Routes, events, schemas, files, commands, or protocols.]

## Failure and recovery
[Expected failures, error behavior, retries, rollback, and operator recovery.]

## Security and privacy
[Trust boundaries, credentials, sensitive data, abuse limits.]

## Compatibility and rollout
[Migration, sequencing, feature flags, fallback, removal plan.]

## Verification
[Tests and real-world proof tied to each requirement.]

## Open questions
- [Decision that still blocks acceptance]

## Related decisions
- [ADR, RFC, plan, issue, or source link]

Example requirement and proof

## Requirements
- R1. An expired share link returns the same public response as an unknown link.

## Verification
- V1. Create one valid and one expired link against the real route harness.
- V2. Assert that both hidden cases return the documented status and body.
- V3. Assert that the expired request does not read document content.

The requirement is observable. The proof checks both response behavior and the sensitive internal boundary. Inspect the generated BMad express technical specification for reliable webhook delivery for a compact same-case output.

Review prompts

Can each requirement be tested without interpreting the author’s intent?
Does the design assign one owner for every durable state transition?
Are failure, privacy, migration, and rollback behavior first-class sections?
Which details belong in an ADR rather than the maintained specification?

See ADR vs RFC vs technical specification before choosing a format. For an inspectable framework example, compare the official Spec Kit documentation with our evidence profile. Reviewed July 19, 2026. Written and maintained by the Plannotator documentation team.

Last modified on August 9, 2026