Someone above you has decided to bring in consultants to review your system. You have opinions about this. Most of them are correct.
But you also have leverage you probably are not using, because the deliverable specification is usually written by someone who does not know what a good one looks like. This post is the list I would hand any engineer whose employer is about to buy an architecture review — the artefacts to demand up front, while the statement of work is still editable.
1. Findings that are specific enough to be wrong
This is the whole test and everything else follows from it.
❌ "The data layer presents scalability concerns."
✅ "The single Postgres primary serves both transactional writes and the
finance team's month-end analytics queries. At the projected 4x volume
this becomes a write-latency incident in ~2 quarters. Fix: read replica
+ query routing at the ORM layer. Est. 3 engineer-weeks."
The first is unfalsifiable. Nobody can check it in six months. It survives any outcome, which is precisely why it gets written.
The second stakes a position. It might be wrong — the volume projection could be off, the finance query might get killed for unrelated reasons — and that is what makes it worth the fee. Someone put judgement on the table where reality can hit it.
Since 2023 this test has become the only one that works. Fluent technical prose is free now; anyone can generate forty pages of well-organised assessment about a codebase they skimmed. Count the falsifiable claims per page and you have a quality metric that AI cannot inflate.
2. A blast radius per finding, not a severity label
HIGH / MEDIUM / LOW is a way of avoiding the question. What you want per finding:
- What breaks first
- Under what condition (load, data volume, concurrency, a specific date)
- Who notices — internal team, one customer segment, everyone
- Whether it degrades or fails hard
A finding without a blast radius cannot be prioritised against the rest of your backlog, which means it will not be actioned, which means the review produced nothing.
3. Effort estimates attached to every recommendation
Not T-shirt sizes. Engineer-weeks, with the assumptions written down.
This one clause does more work than any other, because it forces the reviewer to have thought concretely about implementation instead of gesturing at a target state. "Adopt event-driven architecture" survives contact with a slide. It does not survive "estimate that in engineer-weeks against this repository, listing what you assumed."
Expect and accept ranges. Reject the absence of numbers.
4. An explicit list of what is fine
Demand this one. Ask for the section titled decisions we would not change.
A review returning twenty problems and zero acceptable decisions is not a review, it is a scoping document for the remediation contract that follows it. Real systems contain choices that were correct, and choices that are wrong in ways that will not matter for three years. Naming them proves the reviewer is ranking by impact rather than cataloguing against a reference architecture from a cloud vendor's marketing site.
It is also the part your team most needs. Being told the thing you built is defensible, in writing, by an outsider, is worth something the remediation list is not.
5. Proof they read the incident history
Ask directly: which post-mortems did you read, and what did they change in your conclusions?
Production incident history is the most honest artefact any engineering org produces, because nobody writes a post-mortem to impress a buyer. A reviewer who has read the code but not the incidents has read the fiction and skipped the documentary. Their findings will mirror the architecture diagram rather than the system's actual failure pattern — and those two things diverge in interesting ways in every codebase over about two years old.
The same applies to the people who get paged. If nobody in the on-call rotation was interviewed, the review is incomplete regardless of how thorough the static analysis was.
6. The raw artefacts
Scripts, query outputs, interview notes, the dependency graph in a machine-readable format. You paid for them.
More importantly: the review is a snapshot and your system moves. If you have the scripts, you can re-run the analysis in six months for free. If you have only the PDF, you have bought a one-time observation and you will be buying it again.
7. A walkthrough where you are allowed to argue
Not a presentation to leadership. A working session with the engineers, scheduled, with time for objection.
Two reasons. First, a finding that cannot survive informed challenge from the people who built the system was never solid — and you will find out in that room, not in production. Second, findings your team has argued with become findings your team owns. Findings delivered as a document from outside get treated as an external opinion, and external opinions do not make it into sprint planning.
If a consultancy resists the challenge session, that is your answer about how much the findings are worth.
The one-line version
An architecture review is an engagement to buy a decision, not a document. If the artefacts above are not in the statement of work, what arrives will be a summary of things your team already knew, written more confidently than any of you would have dared.
Frequently Asked Questions
How long should an architecture review take?
Two to four weeks for a system of ordinary complexity. Under two weeks generally means code was read but incident history was not and operators were not interviewed. Beyond six weeks the findings start going stale against a team that is still shipping.
Who should be interviewed during a review?
The on-call rotation first, then the people who wrote the oldest surviving modules, then product. Interviewing only tech leads and architects produces a review of the intended system rather than the real one.
What if we disagree with a finding?
Argue it in the scheduled walkthrough with evidence. A good reviewer will change a conclusion when shown data, and will label which findings are high-confidence versus judgement calls under uncertainty. If nothing is ever labelled uncertain, the confidence is decorative.
Can we just run an AI model over the codebase instead?
For the inventory layer, yes, and you should — dependency mapping and dead-code detection are close to free now. What a model cannot do is rank findings against your organisation's actual capacity, politics and roadmap, because none of that is in the repository.
Should the reviewing firm also do the remediation?
It can, and the context transfer is already paid for. Just make sure the assessment was contracted and priced separately, so the size of the recommended fix does not influence the fee for the diagnosis.
What is the single best clause to add to the SOW?
Named individuals with a committed time percentage. The gap between the person who sold the engagement and the person who performs it is the oldest complaint in professional services and the easiest to close on paper.
Full write-up with the other four engagement types, pricing models and the 30-day test: Software Development Consulting Services: What You Actually Get for the Money.
We do this work at TechCirkle alongside building products — get in touch if you want a scoping call.
Top comments (0)