Part 1 was about connecting the library and querying it. Part 2 was about what’s in it and how it’s curated. Both stop at the same place: you’ve got good answers in a chat window.
That’s not the job. The job produces documents other people act on — a decision record someone reads in eighteen months, a review that tells a client what to fix, a runbook somebody follows at 2am. This is about getting from the library to those.
Start with the ADR, because the library already knows when you need one
Architecture decision records are one of those practices everybody agrees with and few sustain. The reason isn’t writing them. It’s that the hard part of ADR discipline is noticing that a decision was made at all — most of them get made in passing, by whoever was in the room, and nobody thinks “that was architecturally significant” until it’s expensive.
The library front-loads exactly that. Common Decisions (ADR Triggers) is a section type, and it appears throughout. Here’s the GDPR one, trimmed:
- Data residency strategy — Whether to restrict all personal data processing to EU regions, or allow processing elsewhere with transfer safeguards.
- Data deletion pipeline design — How to implement right-to-erasure across primary stores, replicas, backups, caches, and analytics pipelines.
- Pseudonymization strategy — Tokenization vs. hashing vs. format-preserving encryption, and where re-identification keys are stored.
- Backup retention vs. erasure conflict resolution — How to reconcile backup retention policies with deletion requests.
That last one is the tell. “Backups conflict with the right to erasure” is a real, specific, unavoidable collision that a team will absolutely hit and will absolutely not have a written position on. It’s the kind of thing you learn by having the argument once. Having it in a list, before the argument, is the whole point.
So the first artifact is mechanical: pull the triggers for whatever’s in scope, and you have your ADR backlog before you’ve designed anything.
From trigger to actual record
The useful division of labour, once you’re writing one:
The library gives you Context and Options. It knows the decision exists, what the axes are, and what the tradeoff usually turns on. From the data-platform selection file:
Self-managed open source vs managed platform — decided by named operators in steady state, not by architecture quality or by unit economics.
That clause after the dash is doing a lot of work. It’s not “here are the pros and cons,” it’s an opinion about which criterion actually decides it — and it will save you a week of comparing feature matrices that were never going to be the deciding factor.
You give it Decision and Consequences. Those need your constraints: who’s on the team, what’s already under contract, what the budget is, what the client will tolerate. No library has those and no model can infer them.
The best thing I’ve taken from the library into my own ADRs is this one, from the same file:
Decision review trigger — the specific weight change or capability GA that would flip the outcome, recorded as a monitorable condition rather than left implicit.
Most ADRs rot because they capture the decision and not the conditions under which it was right. Two years later nobody can tell whether it still holds, so it gets treated as either permanent or worthless. Writing down what would change your mind — “revisit if the managed offering ships private endpoints” — turns a decision record into something with a live expiry condition. It costs one line.
The design review, as a gap analysis
Second artifact, and the one clients pay for. You have an existing design or an existing estate; you need findings.
The shape that works: pull the relevant checklists, filter to critical, and walk each item against what’s actually deployed. The output isn’t the checklist — it’s the delta, with each finding carrying evidence, a severity, and a recommendation.
This is where priority_filter earns its place, with the caveat from Part 2 that priority inflation is real and Critical is a first pass rather than a verdict. In practice I run critical-only first to get the spine of the review, then widen for anything in a domain that turned out to matter.
Two things make the output an artifact rather than a printout. Every finding needs evidence from the actual environment — a config value, a screenshot, a CLI output — because a finding without evidence is a suggestion, and clients can tell. And items that don’t apply should be recorded as not applicable, with a reason, not silently dropped. A review that only lists problems doesn’t tell anyone what was examined, which means next year’s reviewer starts from zero.
The cutover runbook
Third artifact, and the one where Part 1’s material pays off directly.
Remember the Nutanix Move limitations — no VMs with independent/persistent disks, no PCIe passthrough, no active snapshot chains, no physical-mode RDMs. In a runbook those stop being trivia and become a pre-flight gate: a query you run against the source estate days before cutover, whose output is a list of VMs that will fail, with a remediation each.
The failure entries convert the same way. Goes wrong / happens because / prevent by maps almost directly onto precondition / rollback trigger / verification step. The 24–48 hour storage latency watch after migration isn’t a checklist item in a runbook, it’s an owner, a threshold, and a phone number.
That conversion is the actual work, and it’s yours. The library gives you the raw failure modes; sequencing them against your maintenance window, your change freeze, and your rollback point is the part that makes it a runbook.
The architecture diagram, and the thing it usually leaves out
Fourth artifact, and the one most likely to be produced without provenance.
A diagram is the most persuasive thing an architect hands over and the least accountable. Boxes and arrows read as authoritative regardless of how they got there, and six months later nobody can tell which choices were requirements, which were defaults, and which were whatever the last person drew. The design decisions are all in there; the reasons are all gone.
So draw the ordinary thing, and carry the citations with it.
failures/cost.md on data processing charges.Three things this buys, and the third is the one I care about.
A review conversation that goes somewhere. “Why endpoints rather than NAT” has an answer with a number attached, and the client can disagree with the number rather than with your taste.
A diagram that can be wrong. An annotated choice is falsifiable — if the price changed or the limitation lifted, the citation is where you look. An unannotated box is just a shape.
A record of what you didn’t decide. The numbers only cover choices that came from somewhere. Everything unnumbered is either obvious or unexamined, and being able to see which parts of your own diagram carry no reasoning is worth the annotation on its own.
The mechanics are dull — a numbered badge and a legend row. It’s the discipline that’s rare, and it’s the same discipline as the [S]/[D]/[F]/[C] provenance tags I use on engineering drawings: say where each value came from, so the next person doesn’t have to guess whether it was derived or invented.
Where this stops working
Worth being blunt, because the failure here is seductive.
The library supplies questions. You supply constraints. Ask a model to produce a migration design with the library connected and you will get something that looks like a deliverable — well-structured, correctly cited, plausible throughout. It will also be generic, because nothing in the exchange contained your actual situation: the two applications nobody will let you touch, the contract that expires in March, the team of four, the sponsor who has already told the board a date.
The test I use is simple. If the artifact would be equally true for a different client, it isn’t an artifact — it’s a form. Real design output is specific enough to be wrong, and most of what makes it specific comes from you.
The second failure is subtler: producing more artifacts than anyone will read. It’s now trivially easy to generate an ADR for every trigger in a compliance file. Twelve ADRs nobody reads is worse than three that get referenced, because the twelve teach everyone that ADRs are noise. Use the trigger list to decide what’s significant, then write the few that are.
The series, in one paragraph
Connect a curated library to the model you already use, and the conversation starts somewhere useful instead of at first principles. Know what’s in it and how it was made, so you can tell depth from stubs and treat priorities as a first pass. Then do the part that isn’t retrieval at all — bring your constraints, decide the things only you can decide, and turn the answers into documents someone can act on.
And when the library comes up short on a real job — a provider it barely covers, a failure mode it missed, a claim that has aged out — file it. That is how it got the coverage it already has.
The library doesn’t make you an architect. It removes the part of the job that was never the interesting part, which is remembering all of it.