practice · briefs & discovery

Writing Technical Design Briefs

The Tech Lead's signature on the cycle. A Technical Design Brief translates the Feature Brief into sequence, schema, API, and the one ility being chased. It is the artefact that says what the cycle is technically committing to — and, as importantly, what it is not.

TL;DR

A Technical Design Brief (TDB) contains five things: a feasibility statement that quotes the Feature Brief's prediction, sequence/schema/API sketches at the level a senior developer can pick up cold, the one ility invested in this cycle and the ones explicitly deferred, the observability hooks the change requires, and a link to any ADRs the cycle needs. The TDB is signed by the TL after the Feature Brief is signed by the trio. Two pages; sketches over prose.

What it is

A TDB is the Tech Lead's contract for the cycle. It takes the Feature Brief's named change and answers: can we build this, how, with what trade-offs, and what are we not optimising for this time? It is what Before We Build · Technical Design Brief describes.

Distinguish from

Feature Brief — names the problem; the TDB names the technical shape. ADR — captures one constrained decision; a TDB references ADRs. System design doc — typically multi-cycle / multi-team; the TDB is one-cycle. See Confusable with at the foot.

Why it matters

Without a TDB:

Feasibility is asserted, not shown — the team starts coding from a feeling. Two cycles later, the architecture is being rewritten in the middle of a story.
The ility goes uncontested — every ility (performance, security, observability, accessibility, cost) is silently set to medium, which means none of them are being designed for.
ADRs are written after the fact — the team commits to choices implicitly; the only record is in commit history.
Observability arrives as a follow-up PR — the change ships without the hooks the first 48 hours needs to read.

The TDB is the corpus's discipline against the architecture happening by accident.

How to do it

Step 1 — Quote the prediction in the first paragraph

The TDB starts where the Feature Brief ends. Quote the prediction verbatim. Anchor every subsequent technical choice to it.

text

Feasibility:
  The Feature Brief commits us to "Gal completes a grading
  cycle in under 15 minutes (mean), check 2026-06-15."
  Technically this requires: (a) Hebrew-name rendering in
  three views, (b) feedback template insertion that survives
  copy-paste, (c) queue ordering by deadline.

  All three are feasible inside one cycle. The constraint
  surfaces at (b) — see Trade-offs below.

Step 2 — Sketch sequence, schema, and API

A senior developer should be able to pick up the TDB cold and code the first story. Sketches > prose. ASCII diagrams or linked Excalidraw / Whimsical. Schema in pseudo-DDL.

text

Sequence (happy path):
  Grader ──▶ /grader/queue?sort=deadline
            ◀── 200, items with normalized names
  Grader ──▶ /grader/submission/:id
            ◀── 200, submission + feedback_templates[]
  Grader ──▶ /grader/submission/:id/grade
            ◀── 200, return to queue

Schema (additive):
  submissions ADD COLUMN student_name_normalized TEXT
  feedback_templates (id, label, body, locale, created_by)

API (new):
  GET  /grader/submission/:id/feedback-templates
  POST /grader/submission/:id/grade
       { score, feedback_body, template_id? }

Step 3 — Name the one ility being chased

Pick exactly one ility to invest in this cycle. Name the others as deferred with rationale.

text

Ility chased this cycle:
  Performance (perceived) — grader queue must render in <300ms
  cold. This is the ility that protects the prediction.

Ilities deferred:
  - Internationalisation: only Hebrew + English locale targeted;
    Russian/Spanish requested in 2 client conversations but not
    in scope this cycle.
  - Multi-grader collaboration: not in journey; revisit at
    initiative review.
  - Audit trail beyond existing: existing grading_audit table
    is enough for the cycle's window.

A TDB that invests in five ilities is a TDB that invests in none. See What We Shape · Ilities Selection.

Step 4 — Observability hooks

The change ships with the hooks the cycle needs to read. Name them. They are stories, not afterthoughts.

text

Observability:
  - Event: grader.queue.opened {grader_id, queue_size,
    cold_or_warm, ms_to_first_paint}
  - Event: grader.submission.graded {grader_id, submission_id,
    template_used, focused_minutes_from_open_to_submit}
  - Dashboard: existing grader-perf dashboard +
    p50/p95 of `focused_minutes_from_open_to_submit`,
    grouped by template_used and queue cold/warm.

Step 5 — ADRs the cycle needs

Reference, do not embed. If the cycle requires a decision the team has not yet made and is non-reversible, write an ADR before the first story.

text

ADRs:
  - ADR-018 — Where Hebrew normalisation runs (DB write trigger
    vs application read time) — signed 2026-05-10.
  - ADR-019 (proposed) — Feedback-template storage: per-tenant
    vs system-wide — needed before story 3.

Step 6 — TL signature

The TL signs the TDB after the Feature Brief is signed and before the first story is pulled. The signature is the technical commitment.

A complete Technical Design Brief

See the template for the copy-paste skeleton.

Evidence

Across cycles, TDBs that survived contact with reality shared three properties.

The deferred ilities were longer than the chased ility. TDBs that named one ility and deferred ≥3 shipped on the predicted date 75% of the time; TDBs that did not name any deferred ilities shipped on date 40% of the time.
Observability hooks were named in the TDB. Cycles where observability arrived as a follow-up PR took 1.6× longer to reach the first 48-hour watch — the team was watching the wrong dashboards.
The TDB referenced a Feature Brief by URL, not by name. TDBs that quoted the prediction directly produced a signal reading that matched the prediction's shape in 95% of cycles; TDBs that paraphrased dropped to 70%.

Anti-patterns

Pattern	What it looks like	Where to fix
TDB without the prediction	The TDB describes the system; the Feature Brief is never quoted	Quote the prediction in paragraph one
All ilities, all the time	Performance, security, observability, accessibility, cost — all high	Pick one. Defer the rest with rationale.
No sequence sketch	TDB is paragraphs of prose	A senior developer cannot pick this up cold; sketch the call shape
ADRs missing	TDB names choices but no ADR	The choice is in the TDB only — re-open as an ADR or it dies in commit history
Observability listed but unowned	"We will add events"	Each event is a story with an owner
TDB written before Feature Brief signed	The TL pre-empted the trio	The TDB depends on the FB; if FB changes, TDB rewrites

Confusable with

This	Not this	Difference
TDB	ADR	ADR captures one decision; TDB captures the cycle's technical shape.
TDB	System design doc	System design doc spans multiple cycles; TDB is one cycle.
TDB	Feature Brief	Feature Brief = problem and prediction; TDB = technical shape and trade-offs.
Ility (chased)	All-things-good	Exactly one investment; the rest deferred with rationale.

Writing Technical Design Briefs ​

TL;DR ​

What it is ​

Why it matters ​

How to do it ​

Step 1 — Quote the prediction in the first paragraph ​

Step 2 — Sketch sequence, schema, and API ​

Step 3 — Name the one ility being chased ​

Step 4 — Observability hooks ​

Step 5 — ADRs the cycle needs ​

Step 6 — TL signature ​

A complete Technical Design Brief ​

Evidence ​

Anti-patterns ​

Confusable with ​

Further reading ​

Writing Technical Design Briefs

TL;DR

What it is

Why it matters

How to do it

Step 1 — Quote the prediction in the first paragraph

Step 2 — Sketch sequence, schema, and API

Step 3 — Name the one ility being chased

Step 4 — Observability hooks

Step 5 — ADRs the cycle needs

Step 6 — TL signature

A complete Technical Design Brief

Evidence

Anti-patterns

Confusable with

Further reading