In this article
Start with one incident and one difficult change
A useful diagnostic can begin with two stories: the last incident that disrupted users and the last feature that took unexpectedly long to deliver. Reconstruct the timeline with the team. Which dependency failed, where was evidence missing, and which approvals or handovers delayed recovery? Compare the explanation with logs, deployment history and actual system boundaries.
Distinguish observed facts, hypotheses and preferences. “The database is slow” is a hypothesis until the affected query and workload are identified. “We want microservices” is a proposed solution, not a problem statement. This discipline prevents a diagnostic from becoming a technology shopping list and gives stakeholders a shared description of what needs to improve.
Frame the operating problem before the target system
Start with actors, decisions, inputs, exceptions, volumes, timing, current tools, manual work and consequences of failure. A list of desired features hides why the system exists and which trade-offs matter.
Name the decision owner, mandatory constraints and evidence gaps. Separate facts, assumptions and preferences so the diagnostic does not present an attractive diagram as certainty.
Produce options with explicit trade-offs
Compare buy, configure, integrate, automate and build options against the same criteria: fit, data, security, failure behavior, change, cost categories, delivery risk and ownership. Include the option to stop or reduce scope.
The target architecture should identify system and data authorities, integration contracts, human controls, operational signals and recovery—not only technologies. Record why an option is rejected and what evidence could change the decision.
From an operating problem to a decision
The diagnostic should produce a path the team can act on.
Evidence
Current failures, constraints and change needs.
Options
Compare scope, ownership and trade-offs.
Decision
Record the choice and its review triggers.
First delivery
Test the main risk with a reversible step.
End with a reversible implementation path
Define the smallest end-to-end slice that tests the highest-risk assumption, its acceptance evidence, dependencies and owner. Sequence migrations and integrations so the current operation remains recoverable.
Deliver a risk register, decision records, measurement baseline, release gates and immediate next actions. A diagnostic is complete when a team can approve, defer or reject the work with the same information—not when implementation is made inevitable.
What the decision pack should contain
Deliver a current-system map showing data ownership and critical dependencies, a short evidence register and a prioritised list of risks. For each proposed change, state the user or operating outcome, alternatives considered, effort assumptions and what could invalidate the recommendation. Include an option that improves the existing system without a major redesign.
For example, repeated deployment failures might justify release checks and a configuration correction before a platform migration. The diagnostic should explain why that smaller intervention is sufficient or which evidence shows it is not. A diagram is useful when it clarifies responsibility or a failure path; an exhaustive catalogue of boxes is not a substitute for a decision someone can make.
From observation to an actionable deliverable
Illustrative examples of diagnostic evidence and next steps.
Scroll horizontally to read the table →
| Observed difficulty | Deliverable | Acceptance evidence |
|---|---|---|
| Recovery cannot be rehearsed | Restore procedure and ownership | Restored data checked with the application |
| Releases fail unpredictably | Release controls and rollback path | A staged failed release recovered |
| Changes cross every module | Boundary map and first isolated change | Change delivered through the agreed interface |
Turn the recommendation into a first accepted change
End with a bounded implementation slice, its owner and acceptance evidence. If the priority is recovery, the first deliverable might be a rehearsed restore with a recorded duration and verified application data. If the priority is delivery friction, it might be a single change shipped through a revised release path with a tested rollback.
Record unresolved questions and how they will be answered. Avoid giving precise estimates for unknown integrations without a discovery task. Schedule a review against the original incident or change scenario: did the intervention remove the constraint? The diagnostic earns its value when a team can act, assess the result and revise the next step, rather than merely approve a target architecture presentation.
FAQ / DECISIONS
Frequently asked questions
Is a diagnostic the same as a technical audit?+
Not necessarily. An audit evaluates an existing system; a diagnostic connects the operating problem, current evidence and implementation options to a decision.