template · technical design brief

Technical Design Brief template

Copy-paste skeleton. Two pages. Sketches over prose. Quotes the Feature Brief's prediction in paragraph one.

How to use

The TDB is written after the Feature Brief is signed. Quote the prediction verbatim — paraphrasing is drift. Pick one ility to chase; the rest are deferred with rationale. Reference ADRs by ID; do not embed them.

text

# Technical Design Brief — [feature name]

## Feasibility   (one paragraph)
The Feature Brief commits us to "[QUOTE THE PREDICTION VERBATIM]".
Technically this requires:
  (a) [capability]
  (b) [capability]
  (c) [capability]
All three are feasible inside one cycle. The constraint
surfaces at ([letter]) — see Trade-offs below.

## Sequence   (sketch; ASCII or linked diagram)
[Actor] ──▶ [Endpoint / message]
        ◀── [Response]
[Actor] ──▶ [Endpoint]
        ◀── [Response]

## Schema   (additive / migration)
[Pseudo-DDL. ADD COLUMN, CREATE TABLE, indices, migration notes.]

## API   (new and changed)
[METHOD] /path           — [purpose]
[METHOD] /path           — [purpose]

## Ility chased this cycle   (exactly one)
[Performance / Security / Observability / Accessibility / Cost /
 Reliability / Maintainability — pick one.]
[Why this one — bound to the prediction.]

## Ilities deferred   (with rationale)
- [Ility]: [why deferred; what triggers revisit]
- [Ility]: [why deferred]
- [Ility]: [why deferred]

## Observability hooks   (each is a story)
- Event: [event_name] {fields}
- Event: [event_name] {fields}
- Dashboard: [name + the panel that protects the prediction]

## ADRs
- [ADR-NNN] — [decision title] — signed [date]
- [ADR-NNN] (proposed) — [decision title] — needed before story [N]

## Trade-offs accepted
- [Trade-off 1] — [what we lose, why it's worth it this cycle]
- [Trade-off 2]

## Sign-off
Tech Lead: [Name] · [date]
Reviewed by: [Name (another senior engineer)] · [date]

## Linked artefacts
- Feature Brief: [link]
- ADRs: [links]

Worked example — Grading Shortcut TDB

markdown

# Technical Design Brief — Grading Shortcut

Prediction this serves:
"Gal completes the grading cycle in under 15 minutes."
— Feature Brief, signed 2026-05-04.

## Feasibility
Standard keyboard event handling in the existing grading view.
No new services. One additive event (`teacher.submitted_grade`
with `method:shortcut`). One feature flag. Expected effort:
3 stories at 1-3 days each = single cycle.

## Sequence
  Grader        Frontend            Grading API           Events
    │              │                     │                  │
    │ ⌘+Enter      │                     │                  │
    │─────────────►│                     │                  │
    │              │ POST /exams/:id/    │                  │
    │              │  grade (idempotent) │                  │
    │              │────────────────────►│                  │
    │              │                     │ persist + fire   │
    │              │                     │─────────────────►│
    │              │ 200 OK + next_id    │                  │
    │              │◄────────────────────│                  │
    │              │ navigate to /exams/:next_id            │
    │              │                                        │
    │ next exam loaded                                      │

## Schema
No schema changes. The existing `submissions` table already
supports the persistence shape. New event `teacher.submitted_grade`
with property `method: 'shortcut' | 'click'`.

## API
- POST /exams/:id/grade — existing endpoint, idempotency-key
  header now honoured (ADR-014).
- Response shape unchanged.
- Response now includes `next_in_queue: { id, title } | null`
  so the frontend can prefetch.

## Ility chased this cycle
**Responsiveness** — the perceived-fast threshold. Target: p95
< 500ms from keypress to next-exam-loaded.

## Ilities deferred
- **Accessibility (full)** — keyboard works; screen reader story
  deferred to cycle 6 (named in CS handoff)
- **Multi-language**       — Hebrew language-pack timing concern
  surfaced post-shaping; brief input for next cycle

## Observability hooks
- New event: `teacher.submitted_grade` (with method, exam_id, time)
- New SLI: time-from-keypress-to-next-render p95
- Dashboard panel: `grading-shortcut-overview` (live before flag-on)

## ADRs
- ADR-014 (signed 2026-05-12) — Idempotency keys for grading
  submissions
- ADR-015 (proposed) — Frontend prefetch of next-in-queue; needed
  before story GR-208 (perceived-fast threshold)

## Trade-offs accepted
- We do not refactor the legacy click-path — it stays maintained
  until the flag is removed; the duplication is named and dated
- Tablet UX is not addressed this cycle — deferred to cycle 6

## Sign-off
Tech Lead:   Esti · 2026-05-05
Reviewed by: Roman (senior dev) · 2026-05-06

## Linked artefacts
- Feature Brief: /briefs/grading-shortcut.md
- ADRs:          /adrs/014-idempotency-keys.md ·
                  /adrs/015-prefetch-next-exam.md (proposed)

Where this lives in your project

The TDB lives alongside the Feature Brief — same brief location, separate file. The TL signs after the trio signs the Feature Brief and before the first story is pulled. Linked from the Feature Brief's Linked artefacts section.

What to do if a section resists

Resistance	What it means	Where to go
Cannot quote the Feature Brief's prediction	The Feature Brief is unfinished	Send back to the trio; the TDB is blocked
Sketch became paragraphs	The TL is hiding behind prose	A senior developer should pick this up cold — diagram instead
Five ilities all high	None is actually being designed for	Pick one. Defer the rest with rationale.
No ADRs referenced	The cycle has no non-reversible decisions, or the decisions are happening implicitly	What We Shape · ADR — write before code
Observability listed but unowned	The hooks will ship as follow-up PRs	Each event is a story; assign owners
Trade-offs section is empty	Every trade-off has been silently won by performance (or similar)	Name what is being lost; that is the discipline

Technical Design Brief template ​

Worked example — Grading Shortcut TDB ​

Where this lives in your project ​

What to do if a section resists ​

See also ​

Technical Design Brief template

Worked example — Grading Shortcut TDB

Where this lives in your project

What to do if a section resists

See also