Skip to main content

Module 5: Architecture Decision Records & Reviews: Mistake Clinic

This clinic turns wrong moves into reusable judgment. Use it after each practice page and again before the quiz or checkpoint.

Module-Specific Mistake Radar​

Start with these traps. Replace or extend them with real mistakes from your own work.

Mistake to look forWhere it shows upSymptomRepair evidence
Finishing ADR Writing Workshop with only a final answerADR Writing WorkshopThe work has no failed case, trace, test, proof gap, or design stress point.Add the smallest broken example and show the repair that changes the result.
Finishing Mock Architecture Review with only a final answerMock Architecture ReviewThe work has no failed case, trace, test, proof gap, or design stress point.Add the smallest broken example and show the repair that changes the result.
Finishing Fitness Function Design with only a final answerFitness Function DesignThe work has no failed case, trace, test, proof gap, or design stress point.Add the smallest broken example and show the repair that changes the result.
Finishing Decision Lifecycle Map with only a final answerDecision Lifecycle MapThe work has no failed case, trace, test, proof gap, or design stress point.Add the smallest broken example and show the repair that changes the result.
Treating What an Architecture Decision Is vs a Design Decision as vocabulary instead of a toolWhat an Architecture Decision Is vs a Design DecisionThe explanation names the concept but cannot decide between two cases.Write one example, one non-example, and the rule that separates them.
Treating Why Decisions Need to Be Recorded as vocabulary instead of a toolWhy Decisions Need to Be RecordedThe explanation names the concept but cannot decide between two cases.Write one example, one non-example, and the rule that separates them.

Practice Mistake Checks​

Pull any miss from these checks into your mistake log.

ADR Writing Workshop​

Source: practice/01-adr-writing-workshop.md

Identify the error in each ADR excerpt:

  1. "Decision: We will improve system reliability." (no concrete decision named)
  2. "Context: The team met last Thursday and discussed caching." (history, not context)
  3. "Consequences: Improved performance. Better maintainability. Cleaner code." (all positive; no negative or risk)
  4. "Status: Accepted. Updated 2026-01-02 to reflect new database choice." (in-place override of an Accepted ADR; should supersede)
  5. "Alternatives considered: None." (on a decision with clearly available alternatives - red flag)

Mock Architecture Review​

Source: practice/02-mock-architecture-review.md

Identify the failure mode each excerpt reveals:

  1. A review meeting ends with "let's talk about this more next week." (no decision output)
  2. A PR comment reads "LGTM." (rubber stamp; no substantive engagement)
  3. An agenda reads "Discuss auth architecture." (topic, not a question)
  4. A reviewer only ever asks: "Wouldn't it be better to just X?" (judgment dressed as curiosity)
  5. Participants list: the author, the VP of engineering, 8 cc'd stakeholders. (wrong decision-necessary set)

Fitness Function Design​

Source: practice/03-fitness-function-design.md

Diagnose the problem in each:

  1. A fitness function is added to CI but runs only on a subset of the repo (the author's service). (partial coverage becomes proof of absence)
  2. A rule is recorded as "ADR-0052 says no synchronous billing calls" but no fitness function exists. (documented but not enforced - will rot)
  3. Exemptions are allowed without expiration. (permanent loophole - rule is effectively off for any module with one exemption)
  4. A fitness function reports percentages instead of pass/fail, blocking no PRs. (metric without a threshold is not a gate)
  5. A fitness function duplicates a unit test and adds no architectural value. (misclassified; no one will maintain it)

Decision Lifecycle Map​

Source: practice/04-decision-lifecycle-map.md

Identify the failure mode in each:

  1. An Accepted ADR is edited in place to reflect a new database choice; no superseding ADR exists. (destroys reasoning trail)
  2. An obsolete ADR is deleted from the repo. (removes evidence)
  3. An ADR is marked Deprecated with no replacement planned for 18 months. (deprecation without a path - becomes a zombie)
  4. Two ADRs contradict each other; neither references the other. (orphaned conflict)
  5. A superseding ADR does not link back to the ADR it supersedes. (future readers lose the trail)

Repair Protocol​

For each real mistake:

  1. Reproduce the failure on the smallest example, trace, proof, query, command, or design sketch.
  2. Name the hidden assumption.
  3. Repair the artifact.
  4. Save evidence that changed: failing then passing test, corrected proof step, revised diagram, safer command, benchmark, or review note.
  5. Add one retrieval card beginning with Check... before... or Do not use... when....

Mistake Log​

DateMistakeSymptomRoot causeRepair evidenceRetrieval card
StarterPick one radar row aboveExplain how it would fail in this moduleName the assumptionAdd a counterexample or corrected artifactWrite the card before closing the page

Completion Standard​

  • At least five real mistakes are logged.
  • At least two mistakes include a counterexample or failing test.
  • At least one mistake connects to an older semester skill.
  • At least one correction changes code, a proof, a diagram, a command transcript, a query, or a design decision.