Report review
The reviewer stands in for two readers: the fictive reader (technically educated, no knowledge of the project, cannot ask the author) and the assessor (supervisor, customer, referee), who looks first at title, contents, introduction and summary, and who tends to criticize exactly the passages the author was unsure about. When the content is sound, assessors pick on formal details instead, so formal correctness is worth securing.
Method follows H. Hering, How to Write Technical and Scientific Reports (3rd ed., Springer 2025), Sects. 1, 2.4, 3.8 and the report checklist.
1. Scope and rules
- What is under review: the whole report or one chapter; draft feedback or final check before submission? A draft review emphasizes structure and argument; a final check also covers every formal item.
- What governs: template, institution or customer rules, journal guidelines, page limit, required parts, citation style, style sheet (
style-sheet.adoc). These override the defaults in the checklist; note any conflict instead of silently applying the default. - Find the master file and all included files.
2. Mechanical pass
For AsciiDoc and LaTeX, run the linter on the master document (it follows include:: and \input/\include/\subfile; the format comes from the extension):
python3 scripts/lint_report.py path/to/report.adoc # this skill's directory
python3 scripts/lint_report.py path/to/main.tex
python3 scripts/lint_report.py main.tex --json # machine-readable
python3 scripts/lint_report.py report.adoc --known-abbrev FEM,CAD # abbreviations defined in a list
For LaTeX it also reports \label placed before \caption (the reference then prints the section number), figure captions above the graphic and table captions below the tabular, \includegraphics with both width and height (distortion), "Figure \ref" without a tie, straight double quotes, citation keys missing from the .bib files, and leftover \todo notes or \#\#\# gaps. Abbreviations defined through glossaries/acronym (\newacronym, \acro) count as defined.
For AsciiDoc and LaTeX alike it reports, with file:line: headings swallowed into the previous paragraph (missing blank line, typically between include:: lines), table header rows Asciidoctor will not recognize, unresolved cross-references and citations, uncited reference entries, figures/tables without caption, ID or text reference, figures shown before they are mentioned, figures/tables/lists directly after a heading, lone subsections, level skips, too-deep nesting, hand-typed section numbers (and typed numbers that contradict the heading level), heading punctuation, all-caps or one-word headings, text that continues a heading, number–unit spacing, inconsistent percent style, repeated words, spelling variants of compounds, undefined abbreviations, overlong sentences, and open ###/TODO markers (also inside comments). Every finding is a heuristic: confirm it in context before reporting it.
Also, where available:
asciidoctor -v --failure-level=WARN …(with the project's-rextensions) and read the warnings (missing includes, unresolved references, diagram errors). Rendering shows what the assessor will actually see; problems such as headings swallowed into paragraphs or table headers rendered as data are invisible in the source. If the toolchain is not available, say so, rely on the linter's structural checks, and never praise or vouch for output you have not seen.- LaTeX: build with
latexmk -pdf -interaction=nonstopmode main.tex(or the project's build) and readmain.log: undefined references and citations, multiply defined labels, "Overfull \hbox" (text running into the margin), float-too-large warnings, missing figures. If installed,chktexadds LaTeX typography checks (spacing after abbreviations, dashes, ties). The same caveat applies: without a build, say so. - For a PDF deliverable:
pdfinfo(title metadata, page count),pdffonts(all fonts embedded), and a look at the bookmarks and a few pages at 100 % zoom (sharp figures, no overflowing tables, no lone headings at page bottoms). - For other input (PDF, Word, Markdown), extract the text (e.g.
pdftotext -layout) and do the checks below by reading.
3. Read as the fictive reader
Read the report front to back once without fixing anything; note every place you stumble, guess, or would have to ask. Then check the frame:
- Title: right keywords, accurate, no wrong expectations; consistent between title page, header and metadata.
- Contents: does the outline alone show the backbone? Equal-weight siblings, at least two children per subdivision, specific headings, ≤ 3 numbered levels.
- Introduction: starting situation, relevance, task/goal, route through the report.
- Summary/conclusions: answers the task stated in the introduction; says what was achieved, what was not and why; no new material. Numbers in abstract, results and conclusions agree.
- The three clarities: is it clear (1) what the technical statement is, (2) what was known before and what is new, (3) what the author did personally?
- Argument: each claim supported by data, derivation or citation; doubtful statements either verified or removed ("what is not written cannot be wrong"); no unexplained jumps; no repeated content.
- Reproducibility of methods and tests (equipment, settings, specimens, instruments, formulas with sources).
4. Checklist pass
Go through references/report-checklist.md area by area. Mark each area pass / issues / not applicable. Skip areas that do not apply (e.g. technical drawings), and say so.
5. Consistency sweep
Across all files: terms against the style sheet (or the dominant variant), abbreviations, notation, capitalization of headings and captions, caption punctuation, citation format, cross-reference wording ("Fig." vs "Figure"), numbering of variants/requirements/sub-functions (same number, name and order everywhere).
6. Report
Rank findings by severity:
- Critical — fix before submission: wrong or contradictory results, unsupported or doubtful claims, borrowed material without citation, broken cross-references or citations, missing required parts, reproducibility gaps, open
###/TODO markers, violations of mandatory venue rules. - Major: outline logic, introduction or summary not doing their job, figures/tables without caption, reference or interpretation, inconsistent terminology, unclear actor or meaning, evaluation-table logic errors.
- Minor: notation, typography, wording, layout details.
Each finding: location (file:line, section or page), the problem, why it matters for the reader or assessor (one clause), and a concrete fix (a rewritten heading or sentence, or an exact instruction). Group repeated mechanical issues into one finding with a count and the locations rather than listing each.
Format:
# Review: <report title> (<date>)
Scope: <whole report | chapters>, <draft feedback | final check>. Rules applied: <template/style sheet/defaults>.
## Verdict
<2–4 sentences: ready / ready after critical fixes / needs another draft; the biggest lever for improvement.>
## Fix first
1. <change> — <where> — <effort>
## Critical
1. **<short title>** — `file.adoc:123` (Sect. 4.2). <problem>. <why>. **Fix:** <concrete fix>.
## Major
…
## Minor
…
## What works
<2–4 specific strengths to keep.>
## Checklist status
| Area | Status | Note |
|---|---|---|
## Open items for the author
<questions only the author can answer>
Keep the review usable under deadline pressure:
- Open with Fix first: the 3–7 changes that matter most, in the order to do them, each with a rough effort ("5 min", "needs your data"). Lead with what the assessor will see broken.
- Group repeated or minor items ("12 number–unit spacings, see list") instead of listing each; a review with 30 equal-looking findings hides the five that matter.
- In the conversation, print the verdict, Fix first, and the critical and major findings. When there are more than about 15 findings, write the full report to
review-YYYY-MM-DD.mdnext to the master document and say where it is.
Then offer to fix: mechanical issues (spacing, heading punctuation, captions, IDs, cross-references) can be applied directly; language-level problems go to report-copyedit; missing content needs the author. Do not edit the report during the review unless asked; the review is the deliverable.