Design Decisions & Tradeoff Documentation
Architecture decisions that aren't documented don't survive the SA's departure from the engagement. The developer who extends the integration six months later doesn't know why the pattern was chosen, what alternatives were rejected, or what constraints would break if the design is changed. Architecture Decision Records exist to carry that context forward — and AI makes them fast enough to actually write.
Why architecture decisions disappear — and what it costs
The SA on a Guidewire implementation makes dozens of significant architecture decisions — which integration pattern to use, how to handle the data migration approach, where to place the transformation logic, how to structure the security boundary. In most engagements, fewer than a quarter of those decisions are formally documented. The rest live in the SA's head, in meeting notes that nobody can find, or in Slack threads that expired six months ago.
When the SA rolls off the engagement and the implementation team needs to extend the integration — or when something breaks in production and the team needs to understand the design intent — those undocumented decisions create expensive problems. Teams make changes that violate constraints they didn't know about. They re-debate decisions that were already made for good reasons. They extend designs in ways that break the assumptions the original architecture depended on.
Architecture Decision Records (ADRs) exist to solve this problem. They're short, structured documents that capture each significant decision: what was decided, why, what alternatives were considered, and what the consequences are. AI makes them fast enough to write during the engagement — not as an afterthought when you're rolling off.
The most common undocumented decision that causes production problems in Guidewire implementations is the data migration strategy — specifically, decisions about which legacy data to migrate, which to archive, and which to leave in the legacy system accessible via integration. These decisions are made early, often under pressure, and rarely documented with the constraint context that shaped them. A developer who later extends the system and doesn't know this history will make assumptions that violate the original migration boundary — with consequences ranging from data inconsistency to regulatory reporting errors.
ADR structure and AI-assisted drafting
A good ADR has six components. AI can draft five of them from your notes — fast. The sixth is the one only you can write.
What only the SA can add to the ADR
AI can structure an ADR from your notes. What it cannot add is the context that existed only in conversations — the constraint that emerged in a hallway conversation with the client's enterprise architect, the regulatory guidance that came from a phone call with FSRA that was never written down, the vendor's verbal confirmation that a certain API capability would be available in the next release. This context shapes decisions but rarely makes it into documentation unless the SA puts it there explicitly.
Verbal commitments and confirmations
Vendor claims about roadmap capabilities, client confirmations about system behaviour, regulatory guidance from informal conversations. These shaped your decision and they need to be in the ADR — with the caveat that they're verbal and the confidence level attached to them. Future architects need to know the decision rested partly on an unverified commitment.
Time-bounded constraints
Some constraints exist because of a specific circumstance that may not persist. The procurement process that ruled out Option B. The team skill gap that made Option C non-viable. The regulatory review backlog that made the timeline constraint real. Document when these constraints were true — a future architect revisiting the decision needs to know whether the constraint still applies.
The real reason, not the official reason
Architecture decisions sometimes have a political or organisational dimension alongside the technical one. The option that was technically preferred but rejected because a key stakeholder had a vendor relationship. The approach that was chosen partly because it was the one the client's lead developer was comfortable with. The ADR should reflect the actual decision context, including the non-technical factors that were real influences.
Known future risks
What you know at decision time about how this decision might become wrong in the future. The legacy system's end-of-life timeline. The expected growth in transaction volume. The regulatory changes being discussed that would affect this pattern. Document what you know about the horizon — the review trigger section is where this lives.
Tradeoff documentation discipline — the complete picture
The consequences section of an ADR is where most AI-generated documents fail. AI writes the benefits of the chosen approach thoroughly and treats the constraints as minor caveats. In practice, the constraints are exactly what future architects need to understand — because they're the things that will break if someone makes a change without knowing they exist.
A complete consequences section documents three things: what the decision enables, what it constrains, and what it requires. "Requires" is often the most important — the things that must be true for the design to keep working, that aren't obvious from the design itself, and that would be violated by a seemingly reasonable future change.
Module summary
ADRs are the SA's professional legacy
Decisions that aren't documented don't survive the SA's departure. The constraint that shapes every future extension of the design needs to be in writing, in a place future architects will find it, before you roll off the engagement.
AI drafts structure; SA adds context
AI produces a solid ADR skeleton from your notes. What you must add: verbal commitments with confidence levels, time-bounded constraints, non-technical decision factors, and the specific consequences that only you know from the engagement context.
Complete consequences: enables, constrains, requires
AI writes benefits. You add constraints and requirements. Every hard limit — message size, system capability, team skill boundary — belongs in the consequences section. Future architects need to know what would break, not just what works.
Review triggers carry strategic context
Document when and why the decision should be revisited. Include what you know about future conditions — vendor EOL timelines, expected volume growth, regulatory changes in discussion — with the confidence level attached to each. Future architects need the strategic horizon you saw from your engagement vantage point.
Module 03 — Integration Architecture in Insurance IT — goes deep on the integration design challenges that define most insurance IT SA engagements: Guidewire integration patterns, legacy system connectivity, data migration architecture, and the specific constraints of the Canadian insurance regulatory environment.
Design Decisions & Tradeoff Documentation is done. Continue to Module 03: Integration Architecture in Insurance IT.