What a technical system report should include before implementation begins

What you receive at the end of a Smallbox engagement is a written document. Not a slide deck. Not a list of TODOs. Not a verbal walkthrough that disappears after the call. Typically a 30+ page artefact, plus appendix where useful, delivered as PDF and markdown, that survives the meeting it was discussed in.

This article is about what is in it, and why each section is there. Some of it is the table of contents you would expect. Some of it is the work of choosing what to leave out, which is harder.

What the report is, in two sentences

The report is the bridge between we have a system and some pain and we have a clear next move. It is the diagnostic stage of an engagement — the first engineering deliverable, paid in advance, scoped explicitly, before any implementation work has been agreed.

The diagnostic frame is deliberate. Implementation is the surgery. The report is the diagnosis. A diagnosis that promises surgery before the diagnosis is finished is a sales document, not a report.

What is in the document

Seven sections, in this order. Every section earns its place; nothing is filler.

1. Executive summary (1 page). What the system is, what your stated outcome is — verbatim from intake — and the headline conclusion. Whether the system is in a state where the outcome can be pursued directly, or preparation is needed first. A bulleted list of the 6–10 findings with severity tags. The recommended next step in two sentences. The CEO reads this page; the rest of the report exists to defend it.

2. The system, in plain English (1–2 pages). What the system does for the business. Who uses it. How it runs in one paragraph of prose. The five core entities, named, with one line each. A short subsection on how the business uses this system — drawn from the Business-Use Map — that explains why the findings later are ranked the way they are. A non-technical reader leaves this section understanding the system without having read any code.

3. The system, technically (3–5 pages). Architecture overview with a runtime topology diagram. How the code is organised and how rigorously the layering is enforced in practice. The ER diagram of the core entities. External integrations, listed with purpose and risk profile. Build, deploy, observability — how the system is operated. An engineer joining the team should be able to find their way around after this section.

4. Findings (the bulk of the report). Six to ten ranked findings. Not forty. Each one in the same shape: a short neutral title, a severity and confidence label, a plain English paragraph that the business reader can act on, a technical paragraph that the engineer can act on, evidence — file paths, queries, history stats — and a recommended action with effort range and dependency note. Findings are ordered by severity, then by relevance to the stated outcome. Anything that does not earn its place is in the appendix as an Observation or dropped.

5. What can be safely built directly. A short yes list — the areas where new work can begin without prerequisite cleanup. Many engagements produce more value here than from the findings. The system is not a list of caveats; it is also a list of permissions to proceed.

6. What the system already enables. A cautious section listing business or product moves visible from evidence in the system itself. Unused data the system collects but never surfaces. Manual admin work that could be made self-service. Reporting gaps. Underused integrations. Each item anchored against a concrete observation made during the engagement — not generic strategic advice, not speculation about what the company could do.

7. The recommended implementation package. One option, not three. Scope, sequencing, effort range in weeks, cost range, and the conditions that have to be true before it starts. Shaped by the Change-Safety Plan and the Implementation Strategy that precede it in the report. The package addresses the highest-severity findings, fits a bounded engagement of 2–8 weeks, and is recommendable because the four properties of safe change can be satisfied for the work it contains.

Plus the appendix: the focused-question list with answers from the week-2 working session, the runtime-feasibility note, the endpoint traces, and any supporting artefacts.

What is not in the document

What gets left out matters as much as what gets in.

Not an audit. Audits assign blame. The report assigns next steps. The team that built this is usually still on the team, and a report that reads like a critique is one nobody will let through. The two-voices rule — every finding written in plain English and in technical voice — is partly there to make sure the tone stays diagnostic, not adversarial.

Not a rewrite proposal. The report does not redesign the system in its head. The refactor-or-rewrite question is sometimes a finding, sometimes a recommendation, sometimes parked because the evidence is not yet sufficient — but it is never the default conclusion.

Not a list of forty TODOs. A list of forty observations is overwhelming and useless. The cull from forty candidates down to 6–10 is the work. Findings that do not earn their place are mentioned briefly in an appendix, or dropped. Less is harder to write and more useful to act on.

Not a coverage report. The report does not aspire to comment on every file. It comments on the files that matter for the stated outcome, and says explicitly which areas were inspected with high confidence, which were read-only, and which were not inspected at all.

Not three options to choose between. The recommended implementation package is one option. If the client wants alternatives, they ask. Three-option proposals are sales artefacts; they let the writer avoid the harder work of deciding which option is actually right.

What makes a finding real

Every finding in the report carries the same structure, and the structure is what keeps the report honest.

• A short, neutral title. Not The catastrophic billing problem. Not Auth and billing are pretty bad. Just Auth and billing share a write path.
• A severity tag — Blocking, High, Medium, Low — and a confidence tag — High, Medium, Low. Confidence is not a soft word; it is a record of how many independent sources agreed during the analysis.
• One paragraph in plain English that a non-technical reader can act on.
• One paragraph in technical voice that an engineer can act on.
• Evidence: specific file paths, queries, git statistics, screenshots if relevant.
• A recommendation with an effort range, a label of prerequisite / parallel / independent, and the trust level of the existing safety net for the affected area.

A finding that cannot be expressed in both voices is usually too vague — no plain English means we do not really understand the issue yet — or too jargon-heavy — no technical concreteness means we are describing a feeling, not a fact. Either way, it is not ready, and the report does not ship findings that are not ready.

How the report stays honest about what it does not know

The hardest pages of the report to write are the ones that say we do not know. The pattern is built into every section.

Confidence labels per finding and per flow. Areas labelled high-confidence inspection, reading-only inspection, or out of scope in the appendix. The Change-Safety Plan that names what would have to be true for the next implementation package to be done safely — and what is not yet true.

If a check cannot be answered, the report names it as an uncertainty rather than pretending the answer exists. We could not run the tests during the engagement; the recommended implementation package starts by making them runnable is a real sentence the report is allowed to write.

What this tells you

Two moves, depending on where you are sitting.

If you are commissioning the report — read the executive summary first, then jump to the findings whose titles relate to the change you actually want to make. The middle sections are there to defend the conclusions, not to demand a full read on the day of delivery. Most CTOs read the full document over the following week.

If you are evaluating a different consultant or vendor — the tests above are concrete. Ask whether the deliverable is written. Ask how many findings it will contain. Ask whether each finding will be written in two voices with evidence attached. Ask whether the recommendation is one package or three options. The answers tell you what kind of artefact you are about to receive, before any money changes hands.

Where this fits

The System Report process is what produces the document this article describes. The shape is deliberate and reused per engagement. The contents are unique per system, because the contents are evidence — and evidence is, by definition, generated against the specific codebase, the specific business, and the specific outcome the engagement was scoped against.

If you are deciding whether a system report is worth commissioning, the most useful question is not is it expensive? It is what would I do with the document? The shape above is what the document is for.