The TRD: Contract Before Code

The TRD has five Ratio-standard sections followed by four eng-org extension sections. The five Ratio sections cover what the change is (problem statement, scope, non-scope, and link to the requirement), how it is being done (end-to-end flow, idempotency, retry, async, error handling, data consistency, performance, and rationale over alternatives), database schema changes (or an explicit N/A), API contracts (or an explicit N/A), and acceptance criteria with machine-checkable outcomes.

The four eng-org extension sections add design principles applied to the change, a blast-radius and change-budget declaration (files touched, lines of code, and an explicit rewrite guard), a file-by-file change map that lists every file to be created, edited, or removed with its intent, and a test-tier strategy that maps each acceptance criterion to a unit, integration, e2e, or performance test.

The change budget is declared before coding begins. It names the maximum number of files to be touched and the maximum lines of code. If an implementation exceeds these numbers, the Dev stops and escalates — scope creep is a process failure, not a delivery style.

The file-by-file change map is the handoff artifact from Tech Lead to Dev. It tells each Dev exactly which files are in scope, what state each file will be in (net-new, modified, or deleted), and what the intent of each change is. Devs may not touch files outside this map without stopping and escalating to the Tech Lead.

Once the TRD is approved, it is immutable for the duration of the requirement. If a Dev discovers that the scope must change, the Dev reports back to the Tech Lead, who re-authors the relevant sections and re-gates approval before coding continues.