Engineering Design Review

Proof required

Submit your design document (800–1200 words, excluding diagrams). It must include: a numbered list of at least two alternatives considered with explicit rejection rationale for each; a section titled 'Open Questions' with at least two questions; and at least one diagram (architecture, sequence, or data model — draw.io is free).

What gets checked

• Alternatives are specific and technical — 'Option A: use Redis for caching; rejected because our team has no Redis operational experience and the added operational burden outweighs the latency benefit at current scale' is a valid alternative; 'we considered other options' is not
• Open questions are genuine questions the author cannot answer without external input — 'Should we use Redis or Memcached?' is not an open question if the alternatives section already answered it; 'What is the acceptable p99 latency budget for the new cache lookup?' is a genuine open question that requires stakeholder input
• Diagram accurately represents the proposed state, not the current state — a design document that shows only the existing architecture has not documented the change

Common mistakes

• Writing a design document for a change that is trivial enough to implement without review — renaming a variable or changing a constant does not warrant a design document; the change must have genuine design decisions with tradeoffs
• Listing alternatives without rejection rationale — an alternatives section that says 'Option B: use PostgreSQL JSONB' without explaining why it was rejected leaves the reader unable to evaluate whether the proposed solution is the right choice

Resources

What a verifier looks for

• Engineering Design Triad: M1 produces a design artifact (design document with alternatives, open questions, and diagram) — this is the first of three artifact types required across M1–M3.
• Alternatives must be specific and must include rejection rationale — check that each alternative names a specific technical option and gives a technical reason for rejection.
• Open questions must be genuine unknowns requiring external input — check that each open question cannot be answered from within the design document itself.
• Diagram must show the proposed state — a diagram of the current system without showing the change is not a design artifact.
• Reviewer should be a software or systems engineer with design review experience — the quality of the alternatives analysis and open questions requires technical domain knowledge.

Proof required

Submit: (1) the review record document (400–600 words) covering all four elements above (attendees + roles, objections raised, author responses, open question resolutions); (2) a revised design document incorporating the changes agreed during the review (use tracked changes or a diff appendix to make changes visible).

What gets checked

• Review record names each reviewer with their role and technical background — 'two colleagues' is not a review record; 'Sarah (senior backend engineer, 5 years PostgreSQL experience) and James (infrastructure lead, AWS certified)' is
• At least two objections are documented with the author's specific technical response — 'James raised a concern about the caching invalidation strategy; I explained that we would use a TTL of 60 seconds as a backstop' is a valid entry; 'reviewers had some concerns' is not
• All open questions from M1 are resolved in the review record — either answered, deferred with a named owner and date, or blocked on a named external dependency

Common mistakes

• Presenting to reviewers who have no technical background relevant to the change — a design review requires reviewers who can evaluate the technical tradeoffs; a business stakeholder review is a different activity and does not satisfy this milestone
• Omitting the revised design document — incorporating reviewer feedback into the document is the point of a design review; a review that produces no changes to the document is either a rubber-stamp or a sign that the document was not shared in advance

Resources

What a verifier looks for

• Engineering Design Triad: M2 produces an analysis artifact (review record — the structured analysis of the design by qualified reviewers) — combined with M1's design artifact.
• Review record must name reviewers with roles — verify that named roles demonstrate relevant technical expertise.
• At least two objections must appear in the record with specific technical responses — check that responses address the technical substance, not just acknowledge the concern.
• All open questions from M1 must be resolved — check against the M1 document's Open Questions section.
• Revised design document must show tracked changes — invisible changes cannot be verified.
• Reviewer must be a software or systems engineer — evaluating the quality of the objections and the author's responses requires technical domain knowledge.

Proof required

Submit: (1) the ADR in the format above (400–600 words); (2) a confirmation record (100 words) from the M2 reviewers confirming that the ADR accurately captures the decision made in the review session (email, Slack message screenshot, or signed document — attributing each reviewer by name and role).

What gets checked

• Decision statement is a single, unambiguous choice — 'We will use Redis with a 60-second TTL as the caching layer for the user session data, hosted on AWS ElastiCache' is a decision; 'we decided to improve caching performance' is not a decision
• Consequences section names something that becomes harder — a consequences section that lists only benefits has not honestly captured the tradeoffs; every real design decision makes something harder (e.g. 'cache invalidation logic adds complexity to the write path')
• Reviewer confirmation identifies the reviewers by name and role — an anonymous or generic confirmation does not satisfy the verification requirement

Common mistakes

• Writing an ADR that re-describes the design rather than capturing the decision — an ADR states what was decided in the minimum words necessary; a second design document is not an ADR
• Omitting the alternatives rejected section or leaving it as 'see the design document' — the ADR must be self-contained; a reader who has not read the design document should be able to understand what was rejected and why

Resources

What a verifier looks for

• Engineering Design Triad check: M1–M3 together produce a design artifact (design document with alternatives and diagrams), an analysis artifact (review record with objections and resolutions), and a documentation artifact (ADR — the permanent decision record) — confirm all three are present.
• Decision statement must be unambiguous and specific — check that a reader who has not seen the design document can understand what was decided from the ADR alone.
• Consequences section must name something that becomes harder — a consequences section with only benefits has not honestly captured the tradeoffs.
• Reviewer confirmation must name reviewers — check that the confirmation attributing each reviewer by name and role matches the M2 review record.
• Reviewer must be a software or systems engineer — evaluating the ADR's accuracy and completeness requires technical domain knowledge.
• The Proof Accessibility Rule applies — draw.io, GitHub, and free documentation tools are sufficient; no proprietary tooling is required.