30 May 2024 / Technical leadership / 8 chapters

Check how the decision process fails

From How technical decisions break down as a team grows

Documenting everything creates a stream of trivial records that makes consequential decisions harder to find. Reserve durable records for choices with meaningful alternatives, cross-team effects, difficult reversal or recurring confusion.

Records written after the work to satisfy a process tend to rationalise the implementation rather than capture the actual constraints. Write the proposal before commitment, then update it with the accepted decision.

A central approval board for all changes becomes a queue. Reviewers lose domain context, and teams learn how to frame local work so it can proceed. Central review should focus on named shared contracts and high-consequence choices.

Old decisions left searchable without status are a trap. A careful developer can follow obsolete guidance precisely. Superseded records need a visible marker and a link to the current answer.

Unwritten exceptions travel badly. A senior reviewer may allow one team to diverge for a valid reason but keep the reasoning in conversation. Another team sees the difference and copies it without the constraint. Record exceptions beside the shared rule, including their scope and review condition.

Code may become the only record of product meaning. It shows the current implementation but may not show which behaviour is intentional, which constraint came from another system or which alternative remains unacceptable. Tests help when their names and fixtures carry enough context to explain the rule.

Decision ownership sometimes follows personal reputation. People become informal gates because they know the history, which makes growth harder for newcomers. Put the current answer, source links and review route somewhere the team can access without finding the right person online.

Some assumptions are never revisited. A choice made for one deployment model or customer group may remain long after the condition disappears. Identify assumptions that are likely to change and review them when a relevant event occurs, rather than scheduling a meeting for every record.

All articles