part eight · technical design brief

Technical Design Brief

System-witnessed problem, technical prediction.

The Technical Design Brief is the system-side counterpart to the Feature Brief. Some features need it; some don't. The Tech Lead decides — and the absence of one is itself a decision, recorded.

The TDB exists when the feature contains a technical question whose answer the team does not yet know. It is the artifact that holds the technical Discovery before scope can be drawn at the system level.

When a TDB is written

The Tech Lead writes a TDB when:

• The feature requires a new third-party integration whose failure modes are not yet mapped.
• The feature changes the data model in a way that has migration consequences.
• The feature stresses an existing system in a new direction (load, latency, retention).
• The feature has security or compliance implications that have not been previously decided.
• The feature would be the first of its kind in the codebase — a new pattern.

The Tech Lead does not write a TDB when the feature is a routine extension of existing patterns. Most features fall in this latter category.

Required sections

TECHNICAL DESIGN BRIEF

Title:               Hebrew name support — encoding & migration
Feature:             Grading: native Hebrew name support
Owner:               Yossi (Tech Lead)
Status:              Discovery / Active / Shipped / Spike-required
Last reviewed:       2026-05-05

────────────────────────────────────────────────
1. System-witnessed problem
   What we have observed in the system today. Logs, traces,
   metrics. Witnessed, not assumed.

2. Boundary impact
   What services, schemas, contracts, integrations are touched.

3. Options considered
   2–3 technical directions with trade-offs.

4. Technical prediction
   What change in system behaviour we expect. Baseline, target,
   check date, check method.

5. Spikes required
   Time-boxed investigations that must complete before scope.

6. Ilities selection
   Which non-functional requirements matter for this slice,
   to what level. Recorded as ADR or referenced from one.

7. Risks
   What could go wrong technically, with mitigation plan.

8. Sign-off
   Tech Lead + senior developer + relevant ops. Dates.
────────────────────────────────────────────────

System-witnessed problem

The TDB's first section is the system equivalent of the Feature Brief's experience snapshot. What did we see in the system that named the problem? Logs, traces, query plans, error rates, support escalations, dependency reports.

Application logs from Apr 1–30 show 1,247 occurrences of unicode-encoding-warning on the /api/students/{id}/name endpoint. 89% of those names contain Hebrew unicode forms. Database column students.display_name is stored as UTF-8 but the LMS's frontend rendering fallback is Latin-1, producing mojibake. Workaround patterns in CS data — graders editing names in a spreadsheet — confirm this in the field.

System-witnessed is the technical analogue of witnessed. The Tech Lead has looked at the actual data, not at someone's description of it.

Technical prediction

A specific, measurable technical change.

Technical prediction:
  After the encoding fix and frontend update, occurrences of
  `unicode-encoding-warning` drop to <10/month and `name-edit`
  events from grader accounts drop to <5/week.

Baseline:      1,247 unicode-warning/month, ~120 name-edit
               events/week, captured pre-feature.
Target:        <10 unicode-warning/month, <5 name-edit
               events/week.
Check date:    2026-06-15.
Check method:  Pull the warning count and the name-edit
               event log. No interpretation — counts.

The technical prediction sits next to the Feature Brief's prediction. They check different things — the user-side and the system-side — but both check.

Options and ADR

The TDB lists 2–3 technical options with trade-offs. The chosen option becomes (or references) an ADR in Volume III. The TDB is not the ADR — the TDB documents the discovery; the ADR documents the constrained decision.

If a TDB cannot decide between options, it identifies the spike that would. A spike is a time-boxed investigation, with a deadline and a deliverable. Spikes that go open-ended become Discovery debt.

Spikes

Spikes are short — usually 2–5 days — and produce a written conclusion. The TDB names the spikes required, the time budget, and the question each spike must answer.

Spike: validate that the LMS frontend rendering fallback can be fixed without a frontend deploy. 3 days, owner Yossi. Conclusion to be written 2026-05-12.

Spikes that exceed their budget are escalated to portfolio level — they are evidence that the initiative requires more Discovery investment than was originally scoped.

Ilities selection

Which non-functional requirements matter for this feature, to what level. Listed in the TDB and recorded as an ADR if any of them is non-default.

Ility	Default	Adjusted?
Performance	<200ms p95 on /api/students/*	No change
Availability	99.9% per ADR-12	No change
Accessibility	WCAG 2.2 AA	No change
Security	Auth required, no PII in logs	Re-asserted: confirm names are not logged
Internationalisation	UTF-8 throughout	Adjusted — explicit Hebrew/RTL test coverage required

A feature whose ilities table contains no adjustments is a feature in a known shape. A feature whose ilities table contains adjustments is one where the ADRs need to record what changed.

Sign-off

Tech Lead, plus the most senior developer who will work on the feature, plus any operations engineer whose service is impacted. The TDB is not active until signed.

When a TDB is not written

This is a common error. A team writes a Feature Brief, the feature is non-trivial technically, but no one writes the TDB. The cycle proceeds. The system-side surprise lands at execution. Postmortem traces it to a Discovery gap.

The corpus pattern: when in doubt, the Tech Lead writes a short TDB rather than no TDB. The cost of a half-page TDB is fifteen minutes. The cost of a missing one is sometimes the cycle.

Part 9 — Prediction Writing →